happyskills 0.48.0 → 0.50.0

package/src/commands/install.js

@@ -3,9 +3,15 @@ const { install, install_from_manifest, install_from_lock } = require('../engine
 const { read_lock } = require('../lock/reader')
 const { read_manifest } = require('../manifest/reader')
 const { print_help, print_hint, print_json, print_warn, code } = require('../ui/output')
-const { exit_with_error, UsageError } = require('../utils/errors')
-const { find_project_root } = require('../config/paths')
+const { exit_with_error, UsageError, CliError, AuthError } = require('../utils/errors')
+const { find_project_root, skills_dir, skill_install_dir } = require('../config/paths')
 const { EXIT_CODES } = require('../constants')
+const { get_refs } = require('../api/repos')
+const { extract_version } = require('./versions')
+const { file_exists } = require('../utils/fs')
+const { hash_directory } = require('../lock/integrity')
+const { get_all_locked_skills } = require('../lock/reader')
+const snapshot_storage = require('../snapshot/storage')
 
 const HELP_TEXT = `Usage: happyskills install [<owner>/<skill>[@<version>]] [...] [options]
 
@@ -101,6 +107,79 @@ const run = (args) => catch_errors('Install failed', async () => {
 		throw new UsageError('--version flag cannot be used with multiple skills. Use inline @version syntax instead (e.g., acme/foo@1.2.0 acme/bar@2.0.0).')
 	}
 
+	// § 8.5 — Pre-flight hardening for --fresh.
+	// Closes the § 2 root-cause B (silent fallback to latest when the requested
+	// version isn't on the registry). Done at the command level so the failure
+	// mode surfaces BEFORE any disk mutation.
+	const fresh_snapshots = []
+	if (base_options.fresh) {
+		for (const { skill, version: inline_version } of parsed) {
+			const requested = flag_version || inline_version
+			if (!requested || requested === 'latest') continue
+
+			// (1) Verify the version exists on the registry. Hard-fail if not.
+			const [owner, name] = skill.split('/')
+			const [refs_err, refs] = await get_refs(owner, name)
+			if (refs_err) {
+				// Network failure or skill-not-found. Treat both as VERSION_NOT_FOUND
+				// because we cannot prove the version exists.
+				throw new UsageError(
+					`VERSION_NOT_FOUND: Cannot verify that ${skill}@${requested} exists on the registry (registry unreachable or skill unknown). ` +
+					`--fresh would wipe local content; refusing without confirmation.`
+				)
+			}
+			const available = (refs || []).map(r => extract_version(r.name)).filter(Boolean)
+			if (!available.includes(requested)) {
+				throw new UsageError(
+					`VERSION_NOT_FOUND: ${skill}@${requested} is not on the registry. ` +
+					`Available versions: ${available.join(', ') || '(none)'}. ` +
+					`This was previously a silent-fallback footgun (issue 260523-02 § 2.3) — --fresh now hard-fails.`
+				)
+			}
+
+			// (2) Snapshot before wiping. Always — so a failed install is reversible.
+			const base_dir = skills_dir(base_options.global, base_options.project_root)
+			const skill_dir = skill_install_dir(base_dir, name)
+			const [, dir_present] = await file_exists(skill_dir)
+			if (dir_present) {
+				// (3) Local-edit check. Compare on-disk hash to lock baseline; if
+				// they disagree, require explicit --force-discard-local.
+				const [, lock_data_pre] = await read_lock(base_options.project_root)
+				let has_local_edits = false
+				if (lock_data_pre) {
+					const all = get_all_locked_skills(lock_data_pre)
+					const lock_entry_pre = all[skill] || null
+					if (lock_entry_pre?.base_integrity) {
+						const [, current_hash] = await hash_directory(skill_dir)
+						has_local_edits = current_hash && current_hash !== lock_entry_pre.base_integrity
+					}
+				}
+				if (has_local_edits && !args.flags['force-discard-local']) {
+					throw new UsageError(
+						`LOCAL_EDITS_PRESENT: ${skill} has local edits that would be destroyed by --fresh. ` +
+						`Snapshot first (\`happyskills snapshot create ${skill}\`) and pass --force-discard-local to proceed.`
+					)
+				}
+				const [snap_err, snap] = await snapshot_storage.create({
+					skill_dir,
+					workspace: owner,
+					skill: name,
+					lock_entry: lock_data_pre ? get_all_locked_skills(lock_data_pre)[skill] : null,
+					note: `pre-install-fresh: ${requested}`,
+					is_global: base_options.global,
+					project_root: base_options.project_root
+				})
+				if (snap_err) {
+					throw new CliError(
+						`SNAPSHOT_FAILED: Could not snapshot ${skill} before --fresh wipe. Refusing to proceed.`,
+						EXIT_CODES.ERROR
+					)
+				}
+				fresh_snapshots.push({ skill, snapshot_id: snap.snapshot_id, path: snap.path })
+			}
+		}
+	}
+
 	const results = []
 	const failures = []
 	for (const { skill, version: inline_version } of parsed) {
@@ -121,16 +200,22 @@ const run = (args) => catch_errors('Install failed', async () => {
 		throw new Error(detail)
 	}
 
+	const snapshot_by_skill = Object.fromEntries(fresh_snapshots.map(s => [s.skill, s.snapshot_id]))
+
 	if (args.flags.json) {
-		const items = results.map(({ skill, result }) => ({
-			skill,
-			version: result.version,
-			installed: result.installed || [],
-			skipped: result.skipped || [],
-			skipped_deps: result.skipped_deps || [],
-			warnings: result.warnings || [],
-			forced: result.forced || []
-		}))
+		const items = results.map(({ skill, result }) => {
+			const item = {
+				skill,
+				version: result.version,
+				installed: result.installed || [],
+				skipped: result.skipped || [],
+				skipped_deps: result.skipped_deps || [],
+				warnings: result.warnings || [],
+				forced: result.forced || []
+			}
+			if (snapshot_by_skill[skill]) item.snapshot_id = snapshot_by_skill[skill]
+			return item
+		})
 		const data = results.length === 1 && failures.length === 0 ? items[0] : items
 		if (failures.length > 0) {
 			print_json({ data, errors: failures })

package/src/commands/list.js

@@ -1,6 +1,6 @@
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
-const { verify_lock_disk_consistency } = require('../lock/verify')
+const { verify_lock_disk_consistency, detect_ahead_state } = require('../lock/verify')
 const { skills_dir, skill_install_dir, find_project_root, lock_root } = require('../config/paths')
 const { file_exists, read_json } = require('../utils/fs')
 const { scan_skills_dir, scan_agent_orphan_skills } = require('../utils/skill_scanner')
@@ -76,14 +76,25 @@ const run = (args) => catch_errors('List failed', async () => {
 		return manifest?.type || SKILL_TYPES.SKILL
 	}
 
-	// Compute drift up-front for every managed entry. Cheap (one skill.json read
-	// per skill) and lets both the JSON and human paths report it identically.
+	// Compute drift AND ahead state up-front for every managed entry. Cheap
+	// (one skill.json read per skill, plus an optional CHANGELOG read) and lets
+	// both the JSON and human paths report identically.
+	//
+	// §10.5: drift is narrowed to genuine inconsistency (regression, missing
+	// files); the disk-greater-than-lock case is reported under top-level
+	// status:ahead, not under drift.
 	const drift_by_skill = {}
+	const ahead_by_skill = {}
 	await Promise.all(managed_entries.map(async ([name, data]) => {
 		const short = name.split('/')[1]
 		const dir = skill_install_dir(base_dir, short)
 		const [, drift] = await verify_lock_disk_consistency(data, dir)
-		if (drift && !drift.ok) drift_by_skill[name] = drift
+		if (drift && !drift.ok) {
+			drift_by_skill[name] = drift
+			return
+		}
+		const [, ahead] = await detect_ahead_state(data, dir)
+		if (ahead && ahead.ahead) ahead_by_skill[name] = ahead
 	}))
 
 	if (args.flags.json) {
@@ -93,12 +104,23 @@ const run = (args) => catch_errors('List failed', async () => {
 			const dir = skill_install_dir(base_dir, short)
 			const [, exists] = await file_exists(dir)
 			const drift = drift_by_skill[name]
-			const status = drift ? 'drift' : (exists ? 'installed' : 'missing')
+			const ahead = ahead_by_skill[name]
+			let status
+			if (drift) status = 'drift'
+			else if (ahead) status = 'ahead'
+			else if (exists) status = 'installed'
+			else status = 'missing'
 			const source = data.requested_by?.includes('__root__') ? 'direct' : 'dep'
 			const type = await resolve_type(name, data)
 			const enabled = enabled_map?.get(short) ?? true
 			const entry = { version: data.version, type, source, status, enabled }
 			if (drift) entry.drift = { reason: drift.reason, lock_version: drift.expected, disk_version: drift.actual }
+			if (ahead) entry.ahead = {
+				lock_version: ahead.lock_version,
+				disk_version: ahead.disk_version,
+				has_changelog_entry: ahead.has_changelog_entry || false,
+				changelog_version: ahead.changelog_version || null
+			}
 			skills_map[name] = entry
 		}
 		const external = external_skills.map(s => ({ name: s.name, description: s.description || '' }))
@@ -117,9 +139,12 @@ const run = (args) => catch_errors('List failed', async () => {
 		const dir = skill_install_dir(base_dir, short)
 		const [, exists] = await file_exists(dir)
 		const drift = drift_by_skill[name]
-		const status_label = drift
-			? red(`drift (disk ${drift.actual || 'none'})`)
-			: (exists ? 'installed' : yellow('missing'))
+		const ahead = ahead_by_skill[name]
+		let status_label
+		if (drift) status_label = red(`drift (${drift.reason})`)
+		else if (ahead) status_label = `ahead (disk ${ahead.disk_version})`
+		else if (exists) status_label = 'installed'
+		else status_label = yellow('missing')
 		const source = data.requested_by?.includes('__root__') ? 'direct' : 'dep'
 		const type = await resolve_type(name, data)
 		const display_name = type === SKILL_TYPES.KIT ? `${name} [kit]` : name
@@ -140,10 +165,15 @@ const run = (args) => catch_errors('List failed', async () => {
 	print_table(['Skill', 'Version', 'Source', 'Status', 'Enabled'], rows)
 
 	const drift_count = Object.keys(drift_by_skill).length
+	const ahead_count = Object.keys(ahead_by_skill).length
 	if (drift_count > 0) {
 		console.log()
 		print_warn(`${drift_count} skill(s) drifted: lock and on-disk skill.json disagree.`)
-		print_hint(`Run ${code('happyskills status')} for details, or ${code('happyskills install <skill> --fresh')} to restore.`)
+		print_hint(`Run ${code('happyskills status')} for details, or ${code('happyskills reconcile <skill>')} to repair.`)
+	}
+	if (ahead_count > 0) {
+		console.log()
+		print_info(`${ahead_count} skill(s) ahead of lock — bumped locally, not yet published. Run publish when ready.`)
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 

package/src/commands/publish.js

@@ -260,45 +260,52 @@ const run = (args) => catch_errors('Publish failed', async () => {
 
 	spinner.succeed(`Published ${workspace.slug}/${manifest.name}@${manifest.version}`)
 
-	// Update lock file: set base_commit and base_integrity to new values
+	// Update lock file: set base_commit and base_integrity to new values.
+	// When no lock file exists yet (first publish in a fresh project), we
+	// still create one — otherwise downstream `list`/`status`/`check` would
+	// treat the just-published skill as external. This was a latent bug
+	// pre-260523-02; the spec's lock-as-registry-view principle (§ 4.5) makes
+	// it especially important to keep the lock authoritative.
 	const full_name = full_name_pre
 	let post_publish_entry = null
-	if (!lock_err && lock_data) {
-		const all_skills = get_all_locked_skills(lock_data)
-		const suffix = `/${skill_name}`
-		const lock_key = Object.keys(all_skills).find(k => k.endsWith(suffix))
-		const [hash_err, integrity] = await hash_directory(dir)
-		if (lock_key && all_skills[lock_key]) {
-			const updated_entry = {
-				...all_skills[lock_key],
-				version: manifest.version,
-				ref: push_data?.ref || `refs/tags/v${manifest.version}`,
-				commit: push_data?.commit || null,
-				base_commit: push_data?.commit || null,
-				base_integrity: (!hash_err && integrity) ? integrity : null,
-				dependencies: manifest.dependencies || {}
-			}
-			if (!hash_err && integrity) updated_entry.integrity = integrity
-			delete updated_entry.merge_parents
-			delete updated_entry.conflict_files
-			const updated_skills = update_lock_skills(lock_data, { [lock_key]: updated_entry })
-			await write_lock(project_root, updated_skills)
-			post_publish_entry = updated_entry
-		} else {
-			const new_entry = {
-				version: manifest.version,
-				ref: push_data?.ref || `refs/tags/v${manifest.version}`,
-				commit: push_data?.commit || null,
-				integrity: (!hash_err && integrity) ? integrity : null,
-				base_commit: push_data?.commit || null,
-				base_integrity: (!hash_err && integrity) ? integrity : null,
-				requested_by: ['__root__'],
-				dependencies: manifest.dependencies || {}
-			}
-			const updated_skills = update_lock_skills(lock_data, { [full_name]: new_entry })
-			await write_lock(project_root, updated_skills)
-			post_publish_entry = new_entry
+	const [hash_err, integrity] = await hash_directory(dir)
+
+	const new_entry = {
+		version: manifest.version,
+		ref: push_data?.ref || `refs/tags/v${manifest.version}`,
+		commit: push_data?.commit || null,
+		integrity: (!hash_err && integrity) ? integrity : null,
+		base_commit: push_data?.commit || null,
+		base_integrity: (!hash_err && integrity) ? integrity : null,
+		requested_by: ['__root__'],
+		dependencies: manifest.dependencies || {}
+	}
+
+	const lock_data_to_use = (!lock_err && lock_data) ? lock_data : { lockVersion: 2, generatedAt: new Date().toISOString(), skills: {} }
+	const all_skills = get_all_locked_skills(lock_data_to_use)
+	const suffix = `/${skill_name}`
+	const existing_lock_key = Object.keys(all_skills).find(k => k.endsWith(suffix))
+
+	if (existing_lock_key && all_skills[existing_lock_key]) {
+		const updated_entry = {
+			...all_skills[existing_lock_key],
+			version: manifest.version,
+			ref: push_data?.ref || `refs/tags/v${manifest.version}`,
+			commit: push_data?.commit || null,
+			base_commit: push_data?.commit || null,
+			base_integrity: (!hash_err && integrity) ? integrity : null,
+			dependencies: manifest.dependencies || {}
 		}
+		if (!hash_err && integrity) updated_entry.integrity = integrity
+		delete updated_entry.merge_parents
+		delete updated_entry.conflict_files
+		const updated_skills = update_lock_skills(lock_data_to_use, { [existing_lock_key]: updated_entry })
+		await write_lock(project_root, updated_skills)
+		post_publish_entry = updated_entry
+	} else {
+		const updated_skills = update_lock_skills(lock_data_to_use, { [full_name]: new_entry })
+		await write_lock(project_root, updated_skills)
+		post_publish_entry = new_entry
 	}
 
 	// Post-write verification — confirm the lock entry now agrees with the

package/src/commands/pull.js

@@ -33,6 +33,7 @@ Options:
   --theirs [files]  Take remote version on conflicts (all, or comma-separated file list)
   --ours [files]    Keep local version on conflicts (all, or comma-separated file list)
   --force           Discard all local changes, take remote entirely
+  --rebase          Rebase local edits onto the remote head (snapshot-backed, structured rejection envelope on failure)
   -g, --global      Pull globally installed skill
   --strict          Fail on incompatible dependency ranges instead of warning
   --json            Output as JSON
@@ -40,6 +41,7 @@ Options:
 
 Examples:
   happyskills pull acme/deploy-aws
+  happyskills pull acme/deploy-aws --rebase --json
   happyskills pull acme/deploy-aws --theirs
   happyskills pull acme/deploy-aws --theirs SKILL.md,skill.json --ours references/foo.md
   happyskills pull acme/deploy-aws --json --full-report`
@@ -111,6 +113,44 @@ const run = (args) => catch_errors('Pull failed', async () => {
 	const is_global = args.flags.global || false
 	const full_report = !!(args.flags.json && args.flags['full-report'])
 
+	// § 8.3 — rebase-style pull. Delegates to merge/rebase.js for the snapshot-
+	// 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 })
+		if (err) throw err
+		if (args.flags.json) {
+			print_json({
+				data: result.data || null,
+				next_step: result.next_step || null,
+				error: result.error || null
+			})
+			if (result.next_step) process.exit(EXIT_CODES.ERROR)
+			return
+		}
+		if (result.error) {
+			print_warn(result.error.message || 'Pull --rebase failed')
+			if (result.next_step) print_hint(`Next: ${result.next_step.action}`)
+			process.exit(EXIT_CODES.ERROR)
+			return
+		}
+		if (result.next_step?.action === 'resolve_patch_rejections') {
+			print_warn(`Pull --rebase: ${result.data.patches_rejected.length} patch(es) need resolution.`)
+			for (const r of result.data.patches_rejected) {
+				print_info(`  - ${r.file}: ${r.reason}`)
+			}
+			print_hint(`Restore the pre-rebase state with ${code(`happyskills snapshot restore ${result.data.snapshot_id}`)} if needed.`)
+			process.exit(EXIT_CODES.ERROR)
+			return
+		}
+		if (result.data?.status === 'up_to_date') {
+			print_info(`${skill_name} is already up to date.`)
+			return
+		}
+		print_success(`Rebased ${skill_name} → ${result.data.version || 'latest'}`)
+		return
+	}
+
 	// Parse per-file strategies: --theirs SKILL.md,skill.json --ours references/foo.md
 	const theirs_files = typeof args.flags.theirs === 'string'
 		? new Set(args.flags.theirs.split(',').map(s => s.trim()))

package/src/commands/reconcile.js

@@ -0,0 +1,229 @@
+const path = require('path')
+const fs = require('fs')
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const { read_lock, get_all_locked_skills } = require('../lock/reader')
+const { write_lock, update_lock_skills } = require('../lock/writer')
+const { verify_lock_disk_consistency, detect_ahead_state } = require('../lock/verify')
+const { write_manifest } = require('../manifest/writer')
+const { read_manifest } = require('../manifest/reader')
+const { find_project_root, skills_dir, skill_install_dir, lock_root } = require('../config/paths')
+const { print_help, print_info, print_json, print_warn, print_success, print_hint, code } = require('../ui/output')
+const { exit_with_error, UsageError } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills reconcile <owner/skill> [--apply <action>] [options]
+
+Diagnose drift and apply a deterministic repair, or emit structured options
+for the operator to choose from. Reserved for GENUINE drift only —
+regression, missing files, or unparseable skill.json. The "ahead" state
+(disk version > lock version) is NOT drift; reconcile reports it as a
+non-event and points back to publish.
+
+Arguments:
+  owner/skill                    Skill to inspect
+
+Options:
+  --apply <action>               Execute one of the recommended options directly
+                                 (skips the next_step round-trip).
+  -g, --global                   Operate on globally-installed skills
+  --json                         Output as JSON
+
+Examples:
+  happyskills reconcile acme/deploy-aws --json
+  happyskills reconcile acme/deploy-aws --apply restore_from_lock_version --json`
+
+const SUBTYPE_OPTIONS = {
+	regression: ['restore_from_lock_version', 'accept_disk_as_explicit_downgrade', 'investigate_with_diff'],
+	missing_skill_json: ['restore_from_registry_at_lock_version', 'restore_from_git', 'abandon'],
+	missing_dir: ['reinstall_at_lock_version', 'abandon']
+}
+
+const ACTION_NEXT_STEPS = {
+	regression: 'resolve_regression',
+	missing_skill_json: 'resolve_missing_skill_json',
+	missing_dir: 'resolve_missing_dir'
+}
+
+const resolve_lock_entry = (raw, project_root, is_global) => catch_errors('Failed to resolve lock entry', async () => {
+	const [, lock_data] = await read_lock(lock_root(is_global, project_root))
+	if (!lock_data) return { full: null, lock_entry: null, lock_data: null }
+	const all = get_all_locked_skills(lock_data)
+	let full = raw
+	let lock_entry = all[full] || null
+	if (!lock_entry && !raw.includes('/')) {
+		const suffix = `/${raw}`
+		full = Object.keys(all).find(k => k.endsWith(suffix)) || raw
+		lock_entry = all[full] || null
+	}
+	return { full, lock_entry, lock_data }
+})
+
+const apply_restore_from_lock_version = ({ skill_dir, lock_entry }) => catch_errors('Failed to restore from lock', async () => {
+	const [read_err, manifest] = await read_manifest(skill_dir)
+	if (read_err) throw e('Failed to read skill.json', read_err)
+	manifest.version = lock_entry.version
+	const [write_err] = await write_manifest(skill_dir, manifest)
+	if (write_err) throw e('Failed to write skill.json', write_err)
+	return { applied: 'restore_from_lock_version', new_disk_version: lock_entry.version }
+})
+
+const reconcile_one = (full, lock_entry, skill_dir, options) => catch_errors('Failed to reconcile', async () => {
+	if (!lock_entry) {
+		return {
+			data: { skill: full, no_drift: true, status: 'not_found' },
+			next_step: { action: 'install_first', context: { skill: full, hint: `Skill is not in the lock file. Install it first.` } }
+		}
+	}
+
+	const [verify_err, verify] = await verify_lock_disk_consistency(lock_entry, skill_dir)
+	if (verify_err) throw verify_err[0] || verify_err
+
+	if (verify.ok) {
+		// No genuine drift. Could be clean, modified, or ahead. Reconcile only
+		// reports — it doesn't touch any of these.
+		const [, ahead] = await detect_ahead_state(lock_entry, skill_dir)
+		if (ahead && ahead.ahead) {
+			return {
+				data: {
+					skill: full,
+					no_drift: true,
+					status: 'ahead',
+					ahead: {
+						lock_version: ahead.lock_version,
+						disk_version: ahead.disk_version,
+						has_changelog_entry: ahead.has_changelog_entry || false,
+						changelog_version: ahead.changelog_version || null
+					}
+				},
+				next_step: null,
+				hint: `ahead is a valid precondition for publish, not drift — use \`release\` or \`publish\` to advance the lock, or \`pull\` if the registry has advanced past lock_version`
+			}
+		}
+		return {
+			data: { skill: full, no_drift: true, status: 'clean' },
+			next_step: null
+		}
+	}
+
+	// Genuine drift — handle by subtype.
+	const drift = { reason: verify.reason, lock_version: verify.expected, disk_version: verify.actual }
+	const apply = options.apply || null
+
+	if (verify.reason === 'regression') {
+		if (apply === 'restore_from_lock_version') {
+			const [apply_err, applied] = await apply_restore_from_lock_version({ skill_dir, lock_entry })
+			if (apply_err) throw e('Apply failed', apply_err)
+			return {
+				data: { skill: full, drift_state: 'regression', applied, lock_version: lock_entry.version, disk_version: applied.new_disk_version },
+				next_step: null
+			}
+		}
+		return {
+			data: { skill: full, drift_state: 'regression', lock_version: lock_entry.version, disk_version: drift.disk_version },
+			next_step: {
+				action: 'resolve_regression',
+				context: {
+					skill: full,
+					drift,
+					options: SUBTYPE_OPTIONS.regression,
+					hint: 'Choose: restore_from_lock_version (Edit skill.json back to lock), accept_disk_as_explicit_downgrade (publish disk version as a downgrade), or investigate_with_diff (run happyskills diff first).'
+				}
+			}
+		}
+	}
+
+	if (verify.reason === 'missing_skill_json') {
+		return {
+			data: { skill: full, drift_state: 'missing_skill_json', lock_version: lock_entry.version },
+			next_step: {
+				action: 'resolve_missing_skill_json',
+				context: {
+					skill: full,
+					drift,
+					options: SUBTYPE_OPTIONS.missing_skill_json,
+					hint: 'Choose: restore_from_git (if tracked), restore_from_registry_at_lock_version (verify lock_version is published first), or abandon.'
+				}
+			}
+		}
+	}
+
+	if (verify.reason === 'missing_dir') {
+		return {
+			data: { skill: full, drift_state: 'missing_dir', lock_version: lock_entry.version },
+			next_step: {
+				action: 'resolve_missing_dir',
+				context: {
+					skill: full,
+					drift,
+					options: SUBTYPE_OPTIONS.missing_dir,
+					hint: 'Choose: reinstall_at_lock_version (no --fresh needed; the directory is missing), or abandon (uninstall to clear the stale lock entry).'
+				}
+			}
+		}
+	}
+
+	return {
+		data: { skill: full, drift_state: verify.reason || 'unknown', drift },
+		next_step: {
+			action: 'resolve_unknown_drift',
+			context: { skill: full, drift, hint: 'Unrecognized drift subtype. Surface to the user for manual decision.' }
+		}
+	}
+})
+
+const run = (args) => catch_errors('Reconcile failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const raw = args._[0]
+	if (!raw) throw new UsageError('Usage: happyskills reconcile <owner/skill> [--apply <action>]')
+
+	const project_root = find_project_root()
+	const is_global = !!args.flags.global
+	const base_dir = skills_dir(is_global, project_root)
+	const apply = typeof args.flags.apply === 'string' ? args.flags.apply : null
+
+	const [resolve_err, resolved] = await resolve_lock_entry(raw, project_root, is_global)
+	if (resolve_err) throw e('Failed to resolve skill', resolve_err)
+
+	const full = resolved.full
+	const lock_entry = resolved.lock_entry
+	const short = full && full.includes('/') ? full.split('/')[1] : (raw.includes('/') ? raw.split('/')[1] : raw)
+	const skill_dir = skill_install_dir(base_dir, short)
+
+	const [recon_err, result] = await reconcile_one(full, lock_entry, skill_dir, { apply })
+	if (recon_err) throw e('Reconcile failed', recon_err)
+
+	if (args.flags.json) {
+		const envelope = { data: result.data }
+		if (result.next_step !== undefined) envelope.next_step = result.next_step
+		if (result.hint !== undefined) envelope.hint = result.hint
+		print_json(envelope)
+		return
+	}
+
+	// Human output — terse, lead with plain meaning.
+	if (result.data?.no_drift) {
+		if (result.data.status === 'ahead') {
+			print_info(`${full} is ahead (lock ${result.data.ahead.lock_version}, disk ${result.data.ahead.disk_version}).`)
+			print_hint(`Publish with ${code(`happyskills publish ${full}`)}.`)
+			return
+		}
+		print_success(`${full} is ${result.data.status} — nothing to reconcile.`)
+		return
+	}
+	if (result.data?.applied) {
+		print_success(`Applied ${result.data.applied.applied} — skill.json now at ${result.data.applied.new_disk_version}.`)
+		return
+	}
+	if (result.next_step) {
+		print_warn(`${full} has drift (${result.data.drift_state || 'unknown'}).`)
+		const opts = result.next_step.context?.options || []
+		for (const o of opts) print_info(`  - ${o}`)
+		print_hint(`Pick one and re-run: ${code(`happyskills reconcile ${full} --apply <option>`)}`)
+	}
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+module.exports = { run, reconcile_one, SUBTYPE_OPTIONS, ACTION_NEXT_STEPS }