happyskills 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.11.0] - 2026-06-12
+
+### Added
+
+- Add `--full-report` support to `pull --rebase`. A clean rebase now attaches the same review enrichment as the 3-way merge mode — per-file inline content (`base_content`, `local_content`, `remote_content`, `merged_content`) for every changed file plus a `resolution_steps` array — to the rebase result, so an agent can run a post-merge semantic-coherence review without extra file reads. Previously `--full-report` was accepted but silently ignored on the rebase path, so the LLM-preferred mode produced no review payload.
+
+### Fixed
+
+- Fix re-pull conflict resolution being a silent no-op. After a conflicted `pull` wrote conflict markers, re-running `pull <skill> --theirs` / `--ours` / `--force` returned `up_to_date` and left the markers in place, so the documented conflict-resolution recipes could not work: a conflicted pull advances the lock's `base_commit` to the remote head, after which every re-pull sees no remote changes and short-circuits before the strategy logic runs. Re-pull now resolves pending conflicts before that short-circuit — `--theirs` / `--ours` (global or per-file) keep the chosen side, strip the markers, recompute integrity, and clear the resolved files from `conflict_files`; `--force` falls through to a fast-forward that overwrites even with conflicts pending; and a bare re-pull reports the pending conflict state (`status: conflicts` with the `conflict_files` list) instead of a misleading `up_to_date`.
+
+## [1.10.1] - 2026-06-09
+
+### Fixed
+
+- Fix `uninstall` leaving deep transitive dependencies stranded. Orphan pruning ran a single pass, so removing a skill (or kit / constellation core) pruned its direct dependencies but left behind any *grandchild* dependency whose only parent was one of those now-pruned dependencies — it accumulated as unused cruft in `.agents/skills/` and the lock file. Pruning now cascades to a fixed point, removing the full chain of newly-orphaned dependencies. The data-loss guard is preserved: a dependency that any surviving skill still declares (e.g. a shared satellite like `happyskills-design`) is never pruned, and directly-installed (`__root__`) skills are never swept up.
+
 ## [1.10.0] - 2026-06-06
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "1.10.0",
+	"version": "1.11.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/pull.js

@@ -7,6 +7,7 @@ const { detect_status } = require('../merge/detector')
 const { classify_changes } = require('../merge/comparator')
 const { build_report, enrich_file_content, build_resolution_steps } = require('../merge/report')
 const { three_way_merge } = require('../merge/text_merge')
+const { resolve_markers } = require('../merge/marker_resolve')
 const { merge_skill_json } = require('../merge/json_merge')
 const { merge_changelog } = require('../merge/changelog_merge')
 const { hash_blob } = require('../utils/git_hash')
@@ -117,7 +118,7 @@ const run = (args) => catch_errors('Pull failed', async () => {
 	// first capture/fast-forward/reapply flow with structured rejection envelopes.
 	if (args.flags.rebase) {
 		const { rebase_pull } = require('../merge/rebase')
-		const [err, result] = await rebase_pull(skill_name, { project_root: find_project_root(), is_global })
+		const [err, result] = await rebase_pull(skill_name, { project_root: find_project_root(), is_global, full_report })
 		if (err) throw err
 		if (args.flags.json) {
 			print_json({
@@ -194,6 +195,35 @@ const run = (args) => catch_errors('Pull failed', async () => {
 	const base_dir = skills_dir(is_global, project_root)
 	const skill_dir = skill_install_dir(base_dir, repo)
 
+	// Resolve pending conflict markers from a prior pull — local, no registry.
+	// A conflicted pull advanced base_commit to the remote head, so a re-pull
+	// sees no remote changes and would short-circuit to up_to_date, stranding
+	// the markers in place. When the operator supplies a side (--theirs/--ours,
+	// global or per-file), resolve those files here, before the remote
+	// comparison runs. --force is excluded — it means "re-clone the head", which
+	// the fast-forward block below handles.
+	const pending_conflicts = Array.isArray(lock_entry.conflict_files) ? lock_entry.conflict_files : []
+	const has_pending_resolution = pending_conflicts.length > 0 && strategy !== 'force' &&
+		pending_conflicts.some(f => { const s = file_strategy(f); return s === 'theirs' || s === 'ours' })
+	if (has_pending_resolution) {
+		const [res_err, result] = await resolve_pending_conflicts({
+			skill_dir, lock_entry, lock_data, skill_name, file_strategy,
+			is_global, project_root, conflict_files: pending_conflicts
+		})
+		if (res_err) throw res_err[0]
+		if (args.flags.json) {
+			print_json({ data: result })
+		} else {
+			print_success(`Resolved ${result.resolved.length} conflicted file(s) in ${skill_name}`)
+			if (result.conflict_files.length > 0) {
+				print_warn(`${result.conflict_files.length} file(s) still have unresolved conflicts:`)
+				for (const f of result.conflict_files) console.error(`  - ${f}`)
+				print_hint(`Supply a side for them with ${code('--theirs')}/${code('--ours')}, or resolve the markers by hand.`)
+			}
+		}
+		return
+	}
+
 	const spinner = create_spinner(`Pulling ${skill_name}...`)
 
 	// 2. Detect local modifications
@@ -208,8 +238,24 @@ const run = (args) => catch_errors('Pull failed', async () => {
 	const no_remote_changes = cmp_data.added.length === 0 && cmp_data.removed.length === 0 && cmp_data.modified.length === 0
 
 	// 4. Already up to date?
-	if (no_remote_changes) {
+	// When --force is set with conflicts still pending, do NOT short-circuit —
+	// fall through to the fast-forward block below, which re-clones the head and
+	// overwrites (the true meaning of --force).
+	if (no_remote_changes && !(strategy === 'force' && pending_conflicts.length > 0)) {
 		spinner.stop()
+		if (pending_conflicts.length > 0) {
+			// Markers from a prior pull are still pending and no per-file
+			// resolution strategy was supplied — surface that instead of a
+			// misleading up_to_date so the operator knows resolution is pending.
+			if (args.flags.json) {
+				print_json({ data: { status: 'conflicts', skill: skill_name, conflict_files: pending_conflicts } })
+			} else {
+				print_warn(`${skill_name} has unresolved conflict markers in ${pending_conflicts.length} file(s):`)
+				for (const f of pending_conflicts) console.error(`  - ${f}`)
+				print_hint(`Re-pull with ${code('--theirs')}/${code('--ours')} to pick a side, or resolve the markers by hand.`)
+			}
+			return
+		}
 		if (args.flags.json) {
 			print_json({ data: { status: 'up_to_date', skill: skill_name } })
 		} else {
@@ -611,6 +657,52 @@ const reconcile_dependencies = (skill_dir, skill_name, lock_data, is_global, pro
 		}
 	})
 
+// ─── Pending-conflict resolution (marker-based re-pull) ─────────────────────────
+
+// Resolve pending conflict markers locally by picking a side per file. Pure
+// disk + lock work — no registry interaction, because the conflicted pull that
+// wrote the markers already advanced base_commit to the remote head. Mirrors
+// the 3-way path's lock-update: recompute integrity, then clear resolved files
+// from conflict_files (deleting the key when none remain → status returns to
+// clean, matching post-merge behavior). Files listed in conflict_files but
+// missing on disk, or without a theirs/ours strategy, stay in conflict_files.
+const resolve_pending_conflicts = ({ skill_dir, lock_entry, lock_data, skill_name, file_strategy, is_global, project_root, conflict_files }) =>
+	catch_errors('Failed to resolve pending conflicts', async () => {
+		const resolved = []
+		const unresolved = []
+		for (const rel of conflict_files) {
+			const strat = file_strategy(rel)
+			if (strat !== 'theirs' && strat !== 'ours') { unresolved.push(rel); continue }
+			const full = path.join(skill_dir, rel)
+			let text
+			try {
+				text = await fs.promises.readFile(full, 'utf-8')
+			} catch {
+				// Listed in conflict_files but missing on disk — cannot resolve here.
+				unresolved.push(rel)
+				continue
+			}
+			const side = strat === 'theirs' ? 'remote' : 'local'
+			await fs.promises.writeFile(full, resolve_markers(text, side))
+			resolved.push(rel)
+		}
+
+		const [, new_integrity] = await hash_directory(skill_dir)
+		const updated_entry = {
+			...lock_entry,
+			integrity: new_integrity || lock_entry.integrity,
+			base_integrity: new_integrity || lock_entry.base_integrity
+		}
+		if (unresolved.length > 0) updated_entry.conflict_files = unresolved
+		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) throw wl_err[0]
+
+		const status = unresolved.length > 0 ? 'conflicts' : 'merged'
+		return { status, skill: skill_name, resolved, conflict_files: unresolved }
+	})
+
 const schema = {
 	name: 'pull',
 	audience: 'consumer',
@@ -657,4 +749,4 @@ const schema = {
 	]
 }
 
-module.exports = { run, schema }
+module.exports = { run, schema, resolve_pending_conflicts }

package/src/commands/pull.test.js

@@ -0,0 +1,199 @@
+'use strict'
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+const repos_api = require('../api/repos')
+const pull = require('./pull')
+
+// ─── Harness ────────────────────────────────────────────────────────────────
+
+const MARKERED_SKILL_MD = [
+	'# Deploy AWS',
+	'',
+	'<<<<<<< LOCAL',
+	'local instructions',
+	'=======',
+	'remote instructions',
+	'>>>>>>> REMOTE',
+	'',
+	'trailing section',
+	''
+].join('\n')
+
+// Stub the registry surface used by `run`. compare reports no remote changes
+// (base_commit == head), which is the post-conflict state: a prior conflicted
+// pull already advanced base_commit to head. clone returns base files so the
+// pre-fix detect_status fallback (find_modified_files) stays hermetic.
+const with_stubbed_registry = async (head_commit, fn) => {
+	const orig = { compare: repos_api.compare, clone: repos_api.clone, get_blob: repos_api.get_blob }
+	repos_api.compare = async () => [null, { added: [], removed: [], modified: [], head_commit, head_version: '1.0.1' }]
+	repos_api.clone = async () => [null, { ref: 'refs/tags/v1.0.0', commit: head_commit, files: [
+		{ path: 'SKILL.md', content: Buffer.from('# Deploy AWS\n').toString('base64'), sha: 'sha-base-skillmd' },
+		{ path: 'skill.json', content: Buffer.from('{"name":"deploy-aws","version":"1.0.0"}').toString('base64'), sha: 'sha-base-json' }
+	] }]
+	repos_api.get_blob = async () => [null, { content: Buffer.from('').toString('base64') }]
+	try { return await fn() } finally { Object.assign(repos_api, orig) }
+}
+
+const capture_stdout = async (fn) => {
+	const orig = console.log
+	const lines = []
+	console.log = (...a) => lines.push(a.map(String).join(' '))
+	try { await fn() } finally { console.log = orig }
+	return lines.join('\n')
+}
+
+const setup_conflicted_skill = (head_commit, opts = {}) => {
+	const root = fs.mkdtempSync(path.join(os.tmpdir(), 'hs-pull-test-'))
+	const skill_dir = path.join(root, '.agents', 'skills', 'deploy-aws')
+	fs.mkdirSync(skill_dir, { recursive: true })
+	fs.writeFileSync(path.join(skill_dir, 'SKILL.md'), opts.skill_md || MARKERED_SKILL_MD)
+	fs.writeFileSync(path.join(skill_dir, 'skill.json'), JSON.stringify({ name: 'deploy-aws', version: '1.0.0' }, null, '\t'))
+	const lock = {
+		lockVersion: 2,
+		generatedAt: '2026-06-10T00:00:00.000Z',
+		skills: {
+			'acme/deploy-aws': {
+				version: '1.0.0',
+				ref: 'refs/tags/v1.0.0',
+				commit: head_commit,
+				integrity: 'sha256-stale',
+				base_commit: head_commit,
+				base_integrity: 'sha256-stale',
+				conflict_files: opts.conflict_files || ['SKILL.md'],
+				requested_by: ['__root__'],
+				dependencies: {}
+			}
+		}
+	}
+	fs.writeFileSync(path.join(root, 'skills-lock.json'), JSON.stringify(lock, null, 2))
+	return { root, skill_dir }
+}
+
+const read_lock_entry = (root) =>
+	JSON.parse(fs.readFileSync(path.join(root, 'skills-lock.json'), 'utf-8')).skills['acme/deploy-aws']
+
+const run_pull = (root, head, flags) => with_stubbed_registry(head, () => capture_stdout(async () => {
+	const orig_cwd = process.cwd()
+	process.chdir(root)
+	try { await pull.run({ _: ['acme/deploy-aws'], flags }) } finally { process.chdir(orig_cwd) }
+}))
+
+// ─── §4.1 repro: dead re-pull paths ──────────────────────────────────────────
+
+describe('pull §4.1 — re-pull resolves pending conflict markers', () => {
+	it('--theirs resolves markers to the remote side, clears conflict_files, recomputes integrity', async () => {
+		const head = 'head_commit_abc'
+		const { root, skill_dir } = setup_conflicted_skill(head)
+		try {
+			const out = await run_pull(root, head, { theirs: true, json: true })
+			const env = JSON.parse(out)
+			assert.strictEqual(env.data.status, 'merged', 'status should be merged after full resolution')
+
+			const skill_md = fs.readFileSync(path.join(skill_dir, 'SKILL.md'), 'utf-8')
+			assert.ok(!skill_md.includes('<<<<<<<'), 'LOCAL marker must be gone')
+			assert.ok(!skill_md.includes('>>>>>>>'), 'REMOTE marker must be gone')
+			assert.ok(!skill_md.includes('======='), 'separator must be gone')
+			assert.ok(skill_md.includes('remote instructions'), 'remote side kept')
+			assert.ok(!skill_md.includes('local instructions'), 'local side dropped')
+
+			const entry = read_lock_entry(root)
+			assert.ok(!entry.conflict_files, 'conflict_files cleared from lock')
+			assert.notStrictEqual(entry.integrity, 'sha256-stale', 'integrity recalculated')
+			assert.strictEqual(entry.integrity, entry.base_integrity, 'integrity and base_integrity match (clean)')
+		} finally { fs.rmSync(root, { recursive: true, force: true }) }
+	})
+
+	it('--ours resolves markers to the local side', async () => {
+		const head = 'head_commit_def'
+		const { root, skill_dir } = setup_conflicted_skill(head)
+		try {
+			const out = await run_pull(root, head, { ours: true, json: true })
+			const env = JSON.parse(out)
+			assert.strictEqual(env.data.status, 'merged')
+			const skill_md = fs.readFileSync(path.join(skill_dir, 'SKILL.md'), 'utf-8')
+			assert.ok(skill_md.includes('local instructions'), 'local side kept')
+			assert.ok(!skill_md.includes('remote instructions'), 'remote side dropped')
+			assert.ok(!skill_md.includes('<<<<<<<'))
+		} finally { fs.rmSync(root, { recursive: true, force: true }) }
+	})
+
+	it('bare re-pull surfaces the pending conflict state instead of up_to_date', async () => {
+		const head = 'head_commit_ghi'
+		const { root, skill_dir } = setup_conflicted_skill(head)
+		try {
+			const out = await run_pull(root, head, { json: true })
+			const env = JSON.parse(out)
+			assert.strictEqual(env.data.status, 'conflicts', 'bare re-pull must not say up_to_date when conflicts pending')
+			assert.deepEqual(env.data.conflict_files, ['SKILL.md'])
+			// Markers untouched — nothing was resolved.
+			const skill_md = fs.readFileSync(path.join(skill_dir, 'SKILL.md'), 'utf-8')
+			assert.ok(skill_md.includes('<<<<<<<'), 'markers remain on a bare re-pull')
+		} finally { fs.rmSync(root, { recursive: true, force: true }) }
+	})
+})
+
+// ─── §4.1 wiring: resolve_pending_conflicts ──────────────────────────────────
+
+describe('pull.resolve_pending_conflicts', () => {
+	const make_dir = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-resolve-test-'))
+	const block = (l, r) => `<<<<<<< LOCAL\n${l}\n=======\n${r}\n>>>>>>> REMOTE\n`
+
+	it('applies a per-file strategy mix (theirs for one, ours for another)', async () => {
+		const root = make_dir()
+		try {
+			const skill_dir = path.join(root, '.agents', 'skills', 'deploy-aws')
+			fs.mkdirSync(path.join(skill_dir, 'references'), { recursive: true })
+			fs.writeFileSync(path.join(skill_dir, 'SKILL.md'), block('skill-local', 'skill-remote'))
+			fs.writeFileSync(path.join(skill_dir, 'references', 'foo.md'), block('foo-local', 'foo-remote'))
+			fs.writeFileSync(path.join(skill_dir, 'skill.json'), '{"name":"deploy-aws","version":"1.0.0"}')
+
+			const lock_entry = { version: '1.0.0', base_commit: 'h', integrity: 'sha256-stale', base_integrity: 'sha256-stale', conflict_files: ['SKILL.md', 'references/foo.md'] }
+			const lock_data = { lockVersion: 2, skills: { 'acme/deploy-aws': lock_entry } }
+			const file_strategy = (f) => f === 'SKILL.md' ? 'theirs' : f === 'references/foo.md' ? 'ours' : null
+
+			const [err, result] = await pull.resolve_pending_conflicts({
+				skill_dir, lock_entry, lock_data, skill_name: 'acme/deploy-aws',
+				file_strategy, is_global: false, project_root: root, conflict_files: ['SKILL.md', 'references/foo.md']
+			})
+			assert.ok(!err, 'no error')
+			assert.strictEqual(result.status, 'merged')
+			assert.deepEqual(result.resolved.sort(), ['SKILL.md', 'references/foo.md'])
+
+			assert.strictEqual(fs.readFileSync(path.join(skill_dir, 'SKILL.md'), 'utf-8'), 'skill-remote\n', 'theirs → remote')
+			assert.strictEqual(fs.readFileSync(path.join(skill_dir, 'references', 'foo.md'), 'utf-8'), 'foo-local\n', 'ours → local')
+
+			const entry = JSON.parse(fs.readFileSync(path.join(root, 'skills-lock.json'), 'utf-8')).skills['acme/deploy-aws']
+			assert.ok(!entry.conflict_files, 'conflict_files cleared')
+		} finally { fs.rmSync(root, { recursive: true, force: true }) }
+	})
+
+	it('leaves a file listed in conflict_files but missing on disk unresolved', async () => {
+		const root = make_dir()
+		try {
+			const skill_dir = path.join(root, '.agents', 'skills', 'deploy-aws')
+			fs.mkdirSync(skill_dir, { recursive: true })
+			fs.writeFileSync(path.join(skill_dir, 'SKILL.md'), block('a', 'b'))
+			fs.writeFileSync(path.join(skill_dir, 'skill.json'), '{"name":"deploy-aws","version":"1.0.0"}')
+
+			const lock_entry = { version: '1.0.0', base_commit: 'h', integrity: 'sha256-stale', base_integrity: 'sha256-stale', conflict_files: ['SKILL.md', 'references/gone.md'] }
+			const lock_data = { lockVersion: 2, skills: { 'acme/deploy-aws': lock_entry } }
+			const file_strategy = () => 'theirs'
+
+			const [err, result] = await pull.resolve_pending_conflicts({
+				skill_dir, lock_entry, lock_data, skill_name: 'acme/deploy-aws',
+				file_strategy, is_global: false, project_root: root, conflict_files: ['SKILL.md', 'references/gone.md']
+			})
+			assert.ok(!err)
+			assert.strictEqual(result.status, 'conflicts', 'unresolved file keeps status conflicts')
+			assert.deepEqual(result.resolved, ['SKILL.md'])
+			assert.deepEqual(result.conflict_files, ['references/gone.md'])
+
+			const entry = JSON.parse(fs.readFileSync(path.join(root, 'skills-lock.json'), 'utf-8')).skills['acme/deploy-aws']
+			assert.deepEqual(entry.conflict_files, ['references/gone.md'], 'missing file stays in conflict_files')
+		} finally { fs.rmSync(root, { recursive: true, force: true }) }
+	})
+})

package/src/engine/uninstaller.js

@@ -36,6 +36,37 @@ const find_orphans = (skills, removed_skill) => {
 	return orphans
 }
 
+// Cascading orphan detection. `find_orphans` is single-pass by design (its unit
+// contract): it only reports the DIRECT orphans of `removed_skill`. But pruning a
+// direct orphan A can in turn strand A's own private sub-dependency B — a grandchild
+// that nothing else needs once A is gone. A single pass leaves B behind because A is
+// still in the map (so A both counts as a live requester of B and, via its
+// `dependencies`, as a "surviving declarer" of B).
+//
+// This wrapper closes that gap WITHOUT weakening the data-loss guard. It runs
+// `find_orphans` to a fixed point over a shrinking working copy: each round, the
+// orphans found are physically removed from the map, so the next round sees them as
+// gone — both as requesters (`skills[r]` is now false) and as declarers
+// (`declared_by_survivor` no longer finds them). A skill that ANY surviving skill
+// still declares is never pruned, exactly as before — only skills whose entire
+// requirement chain has been removed cascade out. Terminates because every round
+// deletes at least one entry from a finite map.
+const find_orphans_cascading = (skills, removed_skill) => {
+	const working = { ...skills }
+	delete working[removed_skill]
+
+	const all_orphans = []
+	let round = find_orphans(working, removed_skill)
+	while (round.length > 0) {
+		for (const name of round) {
+			all_orphans.push(name)
+			delete working[name]
+		}
+		round = find_orphans(working, removed_skill)
+	}
+	return all_orphans
+}
+
 const uninstall = (skill, options = {}) => catch_errors('Uninstall failed', async () => {
 	const { global: is_global = false, project_root, agents: agents_flag } = options
 
@@ -64,7 +95,7 @@ const uninstall = (skill, options = {}) => catch_errors('Uninstall failed', asyn
 		}
 	}
 
-	const orphans = find_orphans(all_skills, skill)
+	const orphans = find_orphans_cascading(all_skills, skill)
 	const to_remove = [skill, ...orphans]
 
 	for (const name of to_remove) {
@@ -97,4 +128,4 @@ const uninstall = (skill, options = {}) => catch_errors('Uninstall failed', asyn
 	return { removed: to_remove, orphans_pruned: orphans }
 })
 
-module.exports = { uninstall, find_orphans }
+module.exports = { uninstall, find_orphans, find_orphans_cascading }

package/src/engine/uninstaller.test.js

@@ -1,6 +1,6 @@
 const { describe, it } = require('node:test')
 const assert = require('node:assert')
-const { find_orphans } = require('./uninstaller')
+const { find_orphans, find_orphans_cascading } = require('./uninstaller')
 
 describe('find_orphans', () => {
 	it('returns empty when all skills have requesters in the skills map', () => {
@@ -134,3 +134,122 @@ describe('find_orphans', () => {
 		assert.ok(result.includes('happyskillsai/happyskills-design'))
 	})
 })
+
+describe('find_orphans_cascading', () => {
+	it('cascades: prunes a grandchild stranded once its only parent is orphaned', () => {
+		// Kit K -> A -> B. B is A's private sub-dependency (not listed directly by the
+		// kit). Uninstalling K must prune A (direct orphan) AND B (cascaded orphan).
+		// This is the exact case single-pass find_orphans leaves stranded.
+		const skills = {
+			'acme/_kit-x': { requested_by: ['__root__'], dependencies: { 'acme/a': '^1.0.0' } },
+			'acme/a':      { requested_by: ['acme/_kit-x'], dependencies: { 'acme/b': '^1.0.0' } },
+			'acme/b':      { requested_by: ['acme/_kit-x'], dependencies: {} }
+		}
+		const result = find_orphans_cascading(skills, 'acme/_kit-x')
+		assert.ok(result.includes('acme/a'), 'direct orphan A should be pruned')
+		assert.ok(result.includes('acme/b'), 'cascaded orphan B should be pruned')
+	})
+
+	it('still protects a shared dependency a surviving skill declares (no over-pruning under cascade)', () => {
+		// The data-loss guard must survive the cascade: design is declared by the
+		// surviving happyskills, so uninstalling create-release-skill must NOT prune it
+		// even though we now iterate to a fixed point.
+		const skills = {
+			'happyskillsai/happyskills': {
+				requested_by: ['__root__'],
+				dependencies: { 'happyskillsai/happyskills-design': '^0.1.0' }
+			},
+			'nicolasdao/create-release-skill': {
+				requested_by: ['__root__'],
+				dependencies: { 'happyskillsai/happyskills-design': '^0.9.0' }
+			},
+			'happyskillsai/happyskills-design': {
+				requested_by: ['nicolasdao/create-release-skill']
+			}
+		}
+		const result = find_orphans_cascading(skills, 'nicolasdao/create-release-skill')
+		assert.ok(!result.includes('happyskillsai/happyskills-design'))
+	})
+
+	it('never prunes a user-installed (__root__) skill, even mid-cascade', () => {
+		// K -> A, but A is ALSO directly installed by the user. Removing K orphans
+		// nothing the user still wants: A is __root__-anchored and stays.
+		const skills = {
+			'acme/_kit-x': { requested_by: ['__root__'], dependencies: { 'acme/a': '^1.0.0' } },
+			'acme/a':      { requested_by: ['__root__', 'acme/_kit-x'], dependencies: {} }
+		}
+		const result = find_orphans_cascading(skills, 'acme/_kit-x')
+		assert.deepStrictEqual(result, [])
+	})
+
+	it('halts the cascade at a still-shared mid-chain dependency', () => {
+		// K -> A -> B, but B is ALSO required by an unrelated surviving skill S.
+		// Removing K prunes A, but B must stay because S still needs it.
+		const skills = {
+			'acme/_kit-x': { requested_by: ['__root__'], dependencies: { 'acme/a': '^1.0.0' } },
+			'acme/a':      { requested_by: ['acme/_kit-x'], dependencies: { 'acme/b': '^1.0.0' } },
+			'acme/s':      { requested_by: ['__root__'], dependencies: { 'acme/b': '^1.0.0' } },
+			'acme/b':      { requested_by: ['acme/_kit-x', 'acme/s'], dependencies: {} }
+		}
+		const result = find_orphans_cascading(skills, 'acme/_kit-x')
+		assert.ok(result.includes('acme/a'), 'A is orphaned')
+		assert.ok(!result.includes('acme/b'), 'B is still needed by surviving acme/s')
+	})
+
+	it('constellation: uninstalling the core prunes bundled satellites, keeps shared + opt-in ones', () => {
+		// Models the real happyskills constellation: the core declares 5 bundled
+		// satellites as dependencies. happyskills-design is ALSO declared by a surviving
+		// skill (create-release-skill). collab + stats are OPT-IN — installed directly
+		// (__root__), never dependencies of the core.
+		const skills = {
+			'happyskillsai/happyskills': {
+				requested_by: ['__root__'],
+				dependencies: {
+					'happyskillsai/happyskills-design': '^0.1.0',
+					'happyskillsai/happyskills-publish': '^0.1.0',
+					'happyskillsai/happyskills-sync': '^0.1.0',
+					'happyskillsai/happyskills-search': '^0.1.0',
+					'happyskillsai/happyskills-help': '^0.1.0'
+				}
+			},
+			'nicolasdao/create-release-skill': {
+				requested_by: ['__root__'],
+				dependencies: { 'happyskillsai/happyskills-design': '^0.9.0' }
+			},
+			'happyskillsai/happyskills-design':  { requested_by: ['happyskillsai/happyskills', 'nicolasdao/create-release-skill'], dependencies: {} },
+			'happyskillsai/happyskills-publish': { requested_by: ['happyskillsai/happyskills'], dependencies: {} },
+			'happyskillsai/happyskills-sync':    { requested_by: ['happyskillsai/happyskills'], dependencies: {} },
+			'happyskillsai/happyskills-search':  { requested_by: ['happyskillsai/happyskills'], dependencies: {} },
+			'happyskillsai/happyskills-help':    { requested_by: ['happyskillsai/happyskills'], dependencies: {} },
+			'happyskillsai/happyskills-collab':  { requested_by: ['__root__'], dependencies: {} },
+			'happyskillsai/happyskills-stats':   { requested_by: ['__root__'], dependencies: {} }
+		}
+		const result = find_orphans_cascading(skills, 'happyskillsai/happyskills').sort()
+		assert.deepStrictEqual(result, [
+			'happyskillsai/happyskills-help',
+			'happyskillsai/happyskills-publish',
+			'happyskillsai/happyskills-search',
+			'happyskillsai/happyskills-sync'
+		])
+		// design is shared (create-release-skill still declares it) → kept
+		assert.ok(!result.includes('happyskillsai/happyskills-design'))
+		// collab + stats are opt-in (__root__) → never swept up by a core uninstall
+		assert.ok(!result.includes('happyskillsai/happyskills-collab'))
+		assert.ok(!result.includes('happyskillsai/happyskills-stats'))
+	})
+
+	it('matches find_orphans for a flat kit (no nested sub-dependencies)', () => {
+		// The common curated-kit case: K directly lists A, B, C and none depend on each
+		// other. Single-pass and cascading must agree — cascade changes nothing here.
+		const skills = {
+			'acme/_kit-x': { requested_by: ['__root__'], dependencies: { 'acme/a': '^1', 'acme/b': '^1', 'acme/c': '^1' } },
+			'acme/a':      { requested_by: ['acme/_kit-x'], dependencies: {} },
+			'acme/b':      { requested_by: ['acme/_kit-x'], dependencies: {} },
+			'acme/c':      { requested_by: ['acme/_kit-x'], dependencies: {} }
+		}
+		const single = find_orphans(skills, 'acme/_kit-x').sort()
+		const cascaded = find_orphans_cascading(skills, 'acme/_kit-x').sort()
+		assert.deepStrictEqual(cascaded, ['acme/a', 'acme/b', 'acme/c'])
+		assert.deepStrictEqual(cascaded, single)
+	})
+})

package/src/merge/marker_resolve.js

@@ -0,0 +1,68 @@
+/**
+ * Resolves conflict markers in a file by keeping one side and dropping the
+ * three marker lines. This is the post-conflict semantic of
+ * `git checkout --ours/--theirs`: the markers were already written into the
+ * file by a previous 3-way `pull`, and the operator is now picking a side.
+ *
+ * Marker block (canonical labels from text_merge.js LABELS):
+ *
+ *   <<<<<<< LOCAL
+ *   ...local lines...
+ *   =======
+ *   ...remote lines...
+ *   >>>>>>> REMOTE
+ *
+ * `side` is 'local' (keep the LOCAL section — the `--ours` choice) or
+ * 'remote' (keep the REMOTE section — the `--theirs` choice). Non-marker
+ * content passes through untouched, and multiple blocks in one file are all
+ * resolved. Parsing is stateful, so a bare `=======` outside a block (e.g. a
+ * Markdown setext heading underline) is treated as ordinary content.
+ */
+
+// Canonical 7-char markers. Matched structurally (prefix + label) so the exact
+// label text is not load-bearing, while a standalone separator line must be
+// exactly seven `=`.
+const START_MARKER = /^<{7}(\s|$)/  // <<<<<<< LOCAL
+const SEP_MARKER = /^={7}$/         // =======
+const END_MARKER = /^>{7}(\s|$)/    // >>>>>>> REMOTE
+
+/**
+ * @param {string} text - File content, possibly containing conflict markers.
+ * @param {'local'|'remote'} side - Which side to keep.
+ * @returns {string} The resolved text with the chosen side and no markers.
+ */
+const resolve_markers = (text, side) => {
+	if (side !== 'local' && side !== 'remote')
+		throw new Error(`Invalid side "${side}" — expected 'local' or 'remote'`)
+
+	const lines = String(text == null ? '' : text).split('\n')
+	const out = []
+	let state = 'outside' // 'outside' | 'local' | 'remote'
+
+	for (const line of lines) {
+		if (state === 'outside') {
+			if (START_MARKER.test(line)) { state = 'local'; continue }
+			out.push(line)
+		} else if (state === 'local') {
+			if (SEP_MARKER.test(line)) { state = 'remote'; continue }
+			// Malformed block end without a separator — close it and drop the marker.
+			if (END_MARKER.test(line)) { state = 'outside'; continue }
+			if (side === 'local') out.push(line)
+		} else { // state === 'remote'
+			if (END_MARKER.test(line)) { state = 'outside'; continue }
+			if (side === 'remote') out.push(line)
+		}
+	}
+
+	return out.join('\n')
+}
+
+/**
+ * Whether the text contains at least one conflict-start marker.
+ * @param {string} text
+ * @returns {boolean}
+ */
+const has_markers = (text) =>
+	String(text == null ? '' : text).split('\n').some(line => START_MARKER.test(line))
+
+module.exports = { resolve_markers, has_markers }

package/src/merge/marker_resolve.test.js

@@ -0,0 +1,69 @@
+'use strict'
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+
+const { resolve_markers, has_markers } = require('./marker_resolve')
+
+const block = (local, remote) =>
+	`<<<<<<< LOCAL\n${local}\n=======\n${remote}\n>>>>>>> REMOTE`
+
+describe('marker_resolve.resolve_markers', () => {
+	it('keeps the remote side for --theirs (side=remote)', () => {
+		const text = `intro\n${block('local line', 'remote line')}\noutro`
+		const out = resolve_markers(text, 'remote')
+		assert.strictEqual(out, 'intro\nremote line\noutro')
+	})
+
+	it('keeps the local side for --ours (side=local)', () => {
+		const text = `intro\n${block('local line', 'remote line')}\noutro`
+		const out = resolve_markers(text, 'local')
+		assert.strictEqual(out, 'intro\nlocal line\noutro')
+	})
+
+	it('resolves multiple marker blocks in one file', () => {
+		const text = [
+			'a',
+			block('L1', 'R1'),
+			'b',
+			block('L2', 'R2'),
+			'c'
+		].join('\n')
+		assert.strictEqual(resolve_markers(text, 'remote'), 'a\nR1\nb\nR2\nc')
+		assert.strictEqual(resolve_markers(text, 'local'), 'a\nL1\nb\nL2\nc')
+	})
+
+	it('handles multi-line sections on each side', () => {
+		const text = block('l1\nl2', 'r1\nr2\nr3')
+		assert.strictEqual(resolve_markers(text, 'remote'), 'r1\nr2\nr3')
+		assert.strictEqual(resolve_markers(text, 'local'), 'l1\nl2')
+	})
+
+	it('passes non-marker content through untouched', () => {
+		const text = 'just\nplain\ntext\n'
+		assert.strictEqual(resolve_markers(text, 'remote'), text)
+		assert.strictEqual(resolve_markers(text, 'local'), text)
+	})
+
+	it('does not treat a standalone ======= (setext heading) outside a block as a separator', () => {
+		const text = 'Title\n=======\nbody'
+		assert.strictEqual(resolve_markers(text, 'remote'), text)
+	})
+
+	it('preserves a trailing newline', () => {
+		const text = `${block('L', 'R')}\n`
+		assert.strictEqual(resolve_markers(text, 'remote'), 'R\n')
+	})
+
+	it('rejects an invalid side', () => {
+		assert.throws(() => resolve_markers('x', 'theirs'), /Invalid side/)
+	})
+})
+
+describe('marker_resolve.has_markers', () => {
+	it('detects a conflict-start marker', () => {
+		assert.strictEqual(has_markers(block('a', 'b')), true)
+	})
+	it('returns false for clean text', () => {
+		assert.strictEqual(has_markers('no markers here\nTitle\n=======\n'), false)
+	})
+})

package/src/merge/rebase.js

@@ -9,6 +9,7 @@ const { hash_directory } = require('../lock/integrity')
 const { skills_dir, skill_install_dir, lock_root, find_project_root } = require('../config/paths')
 const { ensure_dir, read_file } = require('../utils/fs')
 const { unified_diff } = require('../utils/text_diff')
+const { enrich_file_content, build_resolution_steps } = require('./report')
 
 // ──────────────────────────────────────────────────────────────────────────────
 // Rebase-style pull (§ 8.3)
@@ -120,12 +121,56 @@ const reapply_patch = (patch, remote_file_content) => {
 	}
 }
 
+// Build the --full-report payload for a successful rebase. Every changed file
+// (remote-vs-base differences ∪ reapplied local patches) gets inline content
+// fields (base/local/remote/merged) so a consuming LLM can review coherence in
+// one pass, plus a deterministic resolution_steps array. Reuses the 3-way
+// report helpers so the shape and step wording match the default mode. There
+// are no conflict markers and no json_conflicts on a clean rebase, so
+// build_resolution_steps emits semantic_review (for changed files) + verify.
+const build_rebase_report = ({ skill_name, version, base_files_map, local_files_map, remote_files_map, merged_files_map, patches }) => {
+	const patch_paths = new Set(patches.map(p => p.path))
+	const changed = new Set(patch_paths)
+	for (const p of new Set([...base_files_map.keys(), ...remote_files_map.keys()])) {
+		if (base_files_map.get(p) !== remote_files_map.get(p)) changed.add(p)
+	}
+
+	const files = []
+	for (const p of changed) {
+		const base = base_files_map.get(p)
+		const local = local_files_map.get(p)
+		const remote = remote_files_map.get(p)
+		const merged = merged_files_map.get(p)
+		const local_changed = patch_paths.has(p)
+		const remote_changed = base !== remote
+		const added = base === undefined
+		let classification
+		if (local_changed && remote_changed) classification = 'both_modified'
+		else if (local_changed) classification = added ? 'local_only_added' : 'local_only_modified'
+		else classification = added ? 'remote_only_added' : 'remote_only_modified'
+
+		const file_entry = { path: p, classification, conflict_written: false, base_sha: null, local_sha: null, remote_sha: null }
+		enrich_file_content(file_entry, { base, local, remote, merged })
+		files.push(file_entry)
+	}
+
+	const report = {
+		skill: skill_name,
+		base_version: null,
+		remote_version: version || null,
+		files,
+		summary: { total: files.length, clean: 0, auto_merged: files.length, conflicted: 0 }
+	}
+	return { report, resolution_steps: build_resolution_steps(report, []) }
+}
+
 const rebase_pull = (skill_name, options = {}) => catch_errors('Pull --rebase failed', async () => {
 	if (!skill_name || !skill_name.includes('/')) {
 		throw new Error('skill_name must be in owner/name format')
 	}
 	const project_root = options.project_root || find_project_root()
 	const is_global = !!options.is_global
+	const full_report = !!options.full_report
 
 	const [lock_err, lock_data] = await read_lock(lock_root(is_global, project_root))
 	if (lock_err || !lock_data) throw new Error('No lock file found')
@@ -304,19 +349,35 @@ const rebase_pull = (skill_name, options = {}) => catch_errors('Pull --rebase fa
 	// Success — drop the snapshot.
 	await snapshot_storage.remove(snap.snapshot_id, { is_global, project_root })
 
-	return {
-		data: {
-			operation: 'pull_rebase',
-			status: applied.length > 0 ? 'rebased' : 'fast_forward',
-			skill: skill_name,
-			fast_forward_to: cmp_data.head_commit,
-			patches_applied: applied,
-			patches_rejected: [],
-			version: cmp_data.head_version || lock_entry.version
-		},
-		next_step: null,
-		error: null
+	const data = {
+		operation: 'pull_rebase',
+		status: applied.length > 0 ? 'rebased' : 'fast_forward',
+		skill: skill_name,
+		fast_forward_to: cmp_data.head_commit,
+		patches_applied: applied,
+		patches_rejected: [],
+		version: cmp_data.head_version || lock_entry.version
 	}
+
+	// --full-report: enrich with inline per-file content + resolution steps for
+	// the operator's semantic-coherence review (Layer 2). The merged result is
+	// now live at skill_dir (post-swap), so read it back as the merged side.
+	if (full_report) {
+		const [, merged_files_map] = await read_dir_files(skill_dir)
+		const { report, resolution_steps } = build_rebase_report({
+			skill_name,
+			version: cmp_data.head_version || lock_entry.version,
+			base_files_map,
+			local_files_map,
+			remote_files_map,
+			merged_files_map: merged_files_map || new Map(),
+			patches
+		})
+		data.report = report
+		data.resolution_steps = resolution_steps
+	}
+
+	return { data, next_step: null, error: null }
 })
 
 module.exports = { rebase_pull, capture_local_patches, reapply_patch, read_dir_files }

package/src/merge/rebase.test.js

@@ -5,7 +5,9 @@ const fs = require('fs')
 const os = require('os')
 const path = require('path')
 
-const { capture_local_patches, reapply_patch, read_dir_files } = require('./rebase')
+const { capture_local_patches, reapply_patch, read_dir_files, rebase_pull } = require('./rebase')
+const repos_api = require('../api/repos')
+const snapshot_storage = require('../snapshot/storage')
 
 describe('rebase.capture_local_patches', () => {
 	it('identifies modified files and produces a patch', () => {
@@ -92,6 +94,105 @@ describe('rebase.reapply_patch', () => {
 	})
 })
 
+describe('rebase.rebase_pull --full-report (§4.2)', () => {
+	const b64 = (s) => Buffer.from(s).toString('base64')
+
+	it('includes inline per-file content and resolution_steps on a clean rebase', async () => {
+		const BASE = 'base123'
+		const HEAD = 'head456'
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), 'hs-rebase-fr-'))
+		const skill_dir = path.join(root, '.agents', 'skills', 'deploy-aws')
+		fs.mkdirSync(skill_dir, { recursive: true })
+		// Local: A modified, B untouched.
+		fs.writeFileSync(path.join(skill_dir, 'A.md'), 'a\nlocal\n')
+		fs.writeFileSync(path.join(skill_dir, 'B.md'), 'b\n')
+		fs.writeFileSync(path.join(skill_dir, 'skill.json'), '{"name":"deploy-aws","version":"1.0.0"}')
+		fs.writeFileSync(path.join(root, 'skills-lock.json'), JSON.stringify({
+			lockVersion: 2,
+			skills: { 'acme/deploy-aws': { version: '1.0.0', base_commit: BASE, integrity: 's', base_integrity: 's', dependencies: {} } }
+		}, null, 2))
+
+		const orig = {
+			compare: repos_api.compare, clone: repos_api.clone,
+			create: snapshot_storage.create, remove: snapshot_storage.remove, restore: snapshot_storage.restore
+		}
+		repos_api.compare = async () => [null, { added: [], removed: [], modified: ['B.md'], head_commit: HEAD, head_version: '1.1.0' }]
+		repos_api.clone = async (owner, repo, ref, opts = {}) => {
+			// Remote modified B, left A and skill.json unchanged from base.
+			const files = opts.commit === BASE
+				? [{ path: 'A.md', content: b64('a\n'), sha: 'sa' }, { path: 'B.md', content: b64('b\n'), sha: 'sb' }, { path: 'skill.json', content: b64('{"name":"deploy-aws","version":"1.0.0"}'), sha: 'sj' }]
+				: [{ path: 'A.md', content: b64('a\n'), sha: 'sa' }, { path: 'B.md', content: b64('b\nremote\n'), sha: 'sb2' }, { path: 'skill.json', content: b64('{"name":"deploy-aws","version":"1.0.0"}'), sha: 'sj' }]
+			return [null, { ref: 'refs/tags/v1.1.0', commit: opts.commit, files }]
+		}
+		snapshot_storage.create = async () => [null, { snapshot_id: 'snap_test' }]
+		snapshot_storage.remove = async () => [null]
+		snapshot_storage.restore = async () => [null]
+
+		try {
+			const [err, result] = await rebase_pull('acme/deploy-aws', { project_root: root, is_global: false, full_report: true })
+			assert.ok(!err, 'rebase_pull should not error')
+			assert.ok(result.data.report, 'report attached to data')
+			assert.ok(Array.isArray(result.data.resolution_steps), 'resolution_steps attached')
+
+			const by_path = Object.fromEntries(result.data.report.files.map(f => [f.path, f]))
+			// A.md — local-only modified; merged keeps the local change.
+			assert.strictEqual(by_path['A.md'].local_content, 'a\nlocal\n')
+			assert.strictEqual(by_path['A.md'].merged_content, 'a\nlocal\n')
+			assert.strictEqual(by_path['A.md'].base_content, 'a\n')
+			// B.md — remote-only modified; merged takes the remote change.
+			assert.strictEqual(by_path['B.md'].remote_content, 'b\nremote\n')
+			assert.strictEqual(by_path['B.md'].merged_content, 'b\nremote\n')
+
+			const actions = result.data.resolution_steps.map(s => s.action)
+			assert.ok(actions.includes('semantic_review'), 'semantic_review step present')
+			assert.ok(actions.includes('verify'), 'verify step present')
+			const sem = result.data.resolution_steps.find(s => s.action === 'semantic_review')
+			assert.ok(sem.files.includes('A.md') && sem.files.includes('B.md'), 'both changed files queued for semantic review')
+		} finally {
+			Object.assign(repos_api, { compare: orig.compare, clone: orig.clone })
+			Object.assign(snapshot_storage, { create: orig.create, remove: orig.remove, restore: orig.restore })
+			fs.rmSync(root, { recursive: true, force: true })
+		}
+	})
+
+	it('omits report fields when full_report is false', async () => {
+		const BASE = 'base123'
+		const HEAD = 'head456'
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), 'hs-rebase-nofr-'))
+		const skill_dir = path.join(root, '.agents', 'skills', 'deploy-aws')
+		fs.mkdirSync(skill_dir, { recursive: true })
+		fs.writeFileSync(path.join(skill_dir, 'A.md'), 'a\nlocal\n')
+		fs.writeFileSync(path.join(skill_dir, 'skill.json'), '{"name":"deploy-aws","version":"1.0.0"}')
+		fs.writeFileSync(path.join(root, 'skills-lock.json'), JSON.stringify({
+			lockVersion: 2,
+			skills: { 'acme/deploy-aws': { version: '1.0.0', base_commit: BASE, integrity: 's', base_integrity: 's', dependencies: {} } }
+		}, null, 2))
+
+		const orig = {
+			compare: repos_api.compare, clone: repos_api.clone,
+			create: snapshot_storage.create, remove: snapshot_storage.remove, restore: snapshot_storage.restore
+		}
+		repos_api.compare = async () => [null, { added: [], removed: [], modified: ['B.md'], head_commit: HEAD, head_version: '1.1.0' }]
+		repos_api.clone = async (owner, repo, ref, opts = {}) => [null, { ref: 'refs/tags/v1.1.0', commit: opts.commit, files: [
+			{ path: 'A.md', content: b64('a\n'), sha: 'sa' }, { path: 'skill.json', content: b64('{"name":"deploy-aws","version":"1.0.0"}'), sha: 'sj' }
+		] }]
+		snapshot_storage.create = async () => [null, { snapshot_id: 'snap_test' }]
+		snapshot_storage.remove = async () => [null]
+		snapshot_storage.restore = async () => [null]
+
+		try {
+			const [err, result] = await rebase_pull('acme/deploy-aws', { project_root: root, is_global: false, full_report: false })
+			assert.ok(!err)
+			assert.strictEqual(result.data.report, undefined, 'no report when full_report is false')
+			assert.strictEqual(result.data.resolution_steps, undefined, 'no resolution_steps when full_report is false')
+		} finally {
+			Object.assign(repos_api, { compare: orig.compare, clone: orig.clone })
+			Object.assign(snapshot_storage, { create: orig.create, remove: orig.remove, restore: orig.restore })
+			fs.rmSync(root, { recursive: true, force: true })
+		}
+	})
+})
+
 describe('rebase.read_dir_files', () => {
 	it('reads all non-dot files recursively', async () => {
 		const root = fs.mkdtempSync(path.join(os.tmpdir(), 'hs-rebase-readdir-'))