happyskills 0.43.1 → 0.44.1

package/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.44.1] - 2026-05-13
+
+### Changed
+- `diff` no longer hard-blocks when the target skill has lock-vs-disk drift. Previously, running `happyskills diff <skill>` against a drifted skill threw a `UsageError` telling the user to run `happyskills install <skill> --fresh` before diffing — but `--fresh` overwrites the on-disk content, destroying the very local state the user was trying to inspect. Drift is exactly the case where diff is most useful as a diagnostic tool. The command now prints a one-line warning (`<skill> has drift: lock <X>, disk <Y>. Diff is shown against the lock-recorded base (<X>).`) and proceeds with the diff. JSON output gains a top-level `drift` field (same `{ reason, lock_version, disk_version }` shape used elsewhere) in `local` and `full` modes, or `null` when clean. `--remote` mode skips the drift probe entirely since it reads nothing from disk. Other drift-aware commands are unchanged — `status`/`check`/`list` still surface drift in their reports, `update` still skips drifted skills to avoid clobbering local work, and the post-write self-checks in `install`/`pull`/`bump`/`publish`/`convert` still throw on inconsistency.
+
+## [0.44.0] - 2026-05-12
+
+### Added
+- Detect lock-vs-disk drift across every CLI command that reads or reports installed-skill state. A new `drift` status is reported whenever the version recorded in `skills-lock.json` does not agree with the version field in the skill's on-disk `skill.json` (or when the install directory or its `skill.json` is missing). The probe is a single `skill.json` read per skill — no API call, no full directory hash. Drift outranks every other status (`clean`/`modified`/`outdated`/`diverged`/`conflicts` for `status`; `up-to-date`/`outdated`/`conflicts` for `check`/`update`) because every other status compares against the lock as a baseline, and drift means the baseline itself is broken. Each result includes a structured `drift: { reason, lock_version, disk_version }` object in `--json` output (`reason` is one of `version_mismatch`, `missing_skill_json`, `missing_dir`). Wired into:
+  - `status` — the headline read-side fix; previously masked drift as `modified (local changes)`.
+  - `check` — previously silent (reported `up-to-date` because it never read disk).
+  - `list` — previously reported the lock's `version` as the installed version, lying when drift existed.
+  - `update` — pre-check now refuses to silently overwrite drift; surfaces it as `drift` in the table and skips affected skills with a remediation hint.
+  - `diff` — refuses with a `UsageError` when the target skill is drifted (the lock's `base_commit` is no longer a coherent comparison baseline; diffing against it produces noise, not signal).
+- Add post-write verification to every command that mutates `skills-lock.json` and skill files together. After the lock is written, each command verifies that the new lock entry agrees with the on-disk `skill.json` and fails loudly (or warns, where appropriate) if they disagree. Closes the prevention half of the drift class — every write path now confirms lock+disk agreement before reporting success. Wired into:
+  - `install` (engine) — throws on mismatch with a `--fresh` remediation hint.
+  - `pull` — throws on the fast-forward path; warns on the three-way merge path (the merger can legitimately resolve `version` to either side, and the user already has conflict review work to do).
+  - `bump` — throws on mismatch; bump touches both files in sequence and is the most direct place where an interruption creates drift.
+  - `publish` — warns on mismatch; the push has already succeeded server-side, so a structural mismatch in the local lock should be surfaced but not block the success report.
+  - `convert` — throws on mismatch; convert generates both files together, so any disagreement is a fresh structural bug.
+- New `cli/src/lock/verify.js` module exporting `verify_lock_disk_consistency(lock_entry, install_dir)` and `describe_drift(result)`. Single source of truth for the lock-vs-disk consistency probe; consumed by `status`, `check`, `list`, `diff`, `update`, `installer`, `pull`, `bump`, `publish`, and `convert`.
+- New regression integration test file `cli/src/integration/drift.test.js` (10 tests, separate from `cli.test.js` to keep that file under the 750-line refactor threshold). Tests reconstruct the exact linwong scenario (lock 0.4.0, disk 0.3.0) and assert that `status`, `check`, `list`, and `diff` all surface drift via the structured `drift` field. Includes coverage for `missing_skill_json`, the "drift outranks modified" invariant, and the "drift overrides up-to-date" invariant. If any of these break, the bug class is back.
+
 ## [0.43.1] - 2026-05-11
 
 ### Fixed

package/package.json

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

package/src/commands/bump.js

@@ -8,8 +8,9 @@ const { find_project_root } = require('../config/paths')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
 const { write_lock, update_lock_skills } = require('../lock/writer')
 const { hash_directory } = require('../lock/integrity')
+const { verify_lock_disk_consistency } = require('../lock/verify')
 const repos_api = require('../api/repos')
-const { print_help, print_success, print_warn, print_json } = require('../ui/output')
+const { print_help, print_success, print_warn, print_json, code } = require('../ui/output')
 const { exit_with_error, UsageError } = require('../utils/errors')
 const { EXIT_CODES } = require('../constants')
 
@@ -99,6 +100,18 @@ const run = (args) => catch_errors('Bump failed', async () => {
 		if (!hash_err && integrity) updated_entry.integrity = integrity
 		const updated_skills = update_lock_skills(lock_data, { [lock_key]: updated_entry })
 		await write_lock(project_root, updated_skills)
+
+		// Post-write verification — bump touches both files, so confirm they
+		// agree before declaring success. An interrupted bump (e.g. process
+		// killed between write_manifest and write_lock above) is exactly the
+		// failure mode this guard exists to catch.
+		const [, verify_result] = await verify_lock_disk_consistency(updated_entry, dir)
+		if (verify_result && !verify_result.ok) {
+			throw new Error(
+				`Bump completed but lock and disk disagree (lock ${verify_result.expected}, disk ${verify_result.actual || 'none'}). ` +
+				`Re-run ${code(`happyskills install ${lock_key} --fresh`)} to restore.`
+			)
+		}
 	}
 
 	if (args.flags.json) {

package/src/commands/check.js

@@ -1,10 +1,11 @@
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { read_lock, get_all_locked_skills, get_via } = require('../lock/reader')
+const { verify_lock_disk_consistency } = require('../lock/verify')
 const repos_api = require('../api/repos')
 const { print_help, print_table, print_json, print_info, print_success, print_warn, print_hint, code } = require('../ui/output')
 const { green, yellow, red } = require('../ui/colors')
 const { exit_with_error } = require('../utils/errors')
-const { find_project_root } = require('../config/paths')
+const { find_project_root, lock_root, skills_dir, skill_install_dir } = require('../config/paths')
 const { EXIT_CODES } = require('../constants')
 
 const HELP_TEXT = `Usage: happyskills check [owner/skill] [options]
@@ -59,17 +60,37 @@ const run = (args) => catch_errors('Check failed', async () => {
 	const skill_names = to_check.map(([name]) => name)
 	const [batch_err, batch_data] = await repos_api.check_updates(skill_names)
 
+	// Verify lock-vs-disk consistency for every skill before classifying. Drift
+	// must outrank up-to-date / outdated / conflicts because all those statuses
+	// trust the lock as a baseline — and drift means the baseline is broken.
+	const base_dir = skills_dir(false, project_root)
+	const drift_by_skill = {}
+	await Promise.all(to_check.map(async ([name, data]) => {
+		const short_name = name.split('/')[1] || name
+		const dir = skill_install_dir(base_dir, short_name)
+		const [, drift] = await verify_lock_disk_consistency(data, dir)
+		if (drift && !drift.ok) drift_by_skill[name] = drift
+	}))
+
 	const results = []
 	if (batch_err) {
 		for (const [name, data] of to_check) {
-			results.push({ skill: name, installed: data.version, latest: 'error', status: 'error', via: get_via(data) })
+			const drift = drift_by_skill[name]
+			if (drift) {
+				results.push({ skill: name, installed: data.version, latest: '-', status: 'drift', via: get_via(data), drift: { reason: drift.reason, lock_version: drift.expected, disk_version: drift.actual } })
+			} else {
+				results.push({ skill: name, installed: data.version, latest: 'error', status: 'error', via: get_via(data) })
+			}
 		}
 	} else {
 		for (const [name, data] of to_check) {
 			const info = batch_data?.results?.[name]
 			const via = get_via(data)
 			const has_conflicts = (data.conflict_files || []).length > 0
-			if (has_conflicts) {
+			const drift = drift_by_skill[name]
+			if (drift) {
+				results.push({ skill: name, installed: data.version, latest: info?.latest_version || '-', status: 'drift', via, drift: { reason: drift.reason, lock_version: drift.expected, disk_version: drift.actual } })
+			} else if (has_conflicts) {
 				results.push({ skill: name, installed: data.version, latest: info?.latest_version || '-', status: 'conflicts', via })
 			} else if (info?.access_denied) {
 				results.push({ skill: name, installed: data.version, latest: '-', status: 'no-access', via })
@@ -90,7 +111,8 @@ const run = (args) => catch_errors('Check failed', async () => {
 		const outdated_count = results.filter(r => r.status === 'outdated').length
 		const up_to_date_count = results.filter(r => r.status === 'up-to-date').length
 		const conflicts_count = results.filter(r => r.status === 'conflicts').length
-		print_json({ data: { results, outdated_count, up_to_date_count, conflicts_count } })
+		const drift_count = results.filter(r => r.status === 'drift').length
+		print_json({ data: { results, outdated_count, up_to_date_count, conflicts_count, drift_count } })
 		return
 	}
 
@@ -98,6 +120,7 @@ const run = (args) => catch_errors('Check failed', async () => {
 		'up-to-date': green,
 		'outdated': yellow,
 		'conflicts': red,
+		'drift': red,
 		'no-access': yellow,
 		'error': red,
 		'unknown': (s) => s
@@ -121,7 +144,17 @@ const run = (args) => catch_errors('Check failed', async () => {
 
 	const outdated = results.filter(r => r.status === 'outdated')
 	const conflicts = results.filter(r => r.status === 'conflicts')
+	const drifted = results.filter(r => r.status === 'drift')
 	const no_access = results.filter(r => r.status === 'no-access')
+	if (drifted.length > 0) {
+		console.log()
+		print_warn(`${drifted.length} skill(s) drifted: lock and on-disk skill.json disagree.`)
+		for (const d of drifted) {
+			const disk = d.drift?.disk_version || 'none'
+			console.error(`  - ${d.skill} (lock ${d.drift?.lock_version}, disk ${disk})`)
+		}
+		print_hint(`Run ${code('happyskills status')} for details, or ${code('happyskills install <skill> --fresh')} to restore.`)
+	}
 	if (conflicts.length > 0) {
 		console.log()
 		print_warn(`${conflicts.length} skill(s) have unresolved merge conflicts.`)
@@ -130,7 +163,7 @@ const run = (args) => catch_errors('Check failed', async () => {
 	if (outdated.length > 0) {
 		console.log()
 		print_info(`Run ${code('happyskills update --all')} to upgrade ${outdated.length} skill(s).`)
-	} else if (conflicts.length === 0 && results.every(r => r.status === 'up-to-date')) {
+	} else if (conflicts.length === 0 && drifted.length === 0 && results.every(r => r.status === 'up-to-date')) {
 		console.log()
 		print_success('All skills are up to date.')
 	}

package/src/commands/convert.js

@@ -11,6 +11,7 @@ const { write_manifest } = require('../manifest/writer')
 const { read_lock } = require('../lock/reader')
 const { write_lock, update_lock_skills } = require('../lock/writer')
 const { hash_directory } = require('../lock/integrity')
+const { verify_lock_disk_consistency } = require('../lock/verify')
 const { skills_dir, find_project_root, lock_root } = require('../config/paths')
 const { file_exists } = require('../utils/fs')
 const { resolve_agents, link_to_agents } = require('../agents')
@@ -201,6 +202,17 @@ const run = (args) => catch_errors('Convert failed', async () => {
 	const [lock_err] = await write_lock(lock_dir, new_skills)
 	if (lock_err) { pub_spinner.fail('Failed to write lock file'); throw e('Lock write failed', lock_err) }
 
+	// Post-write verification — convert wrote both skill.json and the lock,
+	// so confirm they agree before declaring success.
+	const [, verify_result] = await verify_lock_disk_consistency(updates[full_name], skill_dir)
+	if (verify_result && !verify_result.ok) {
+		pub_spinner.fail('Convert verification failed')
+		throw new Error(
+			`Convert completed but lock and disk disagree (lock ${verify_result.expected}, disk ${verify_result.actual || 'none'}). ` +
+			`Re-run convert or fix skill.json manually before publishing.`
+		)
+	}
+
 	// Link to detected agents (non-fatal — warnings only)
 	const linked_agents = []
 	const [agents_err, agents_result] = await resolve_agents(args.flags.agents || undefined)

package/src/commands/diff.js

@@ -7,6 +7,7 @@ const { build_report } = require('../merge/report')
 const { hash_blob } = require('../utils/git_hash')
 const { unified_diff } = require('../utils/text_diff')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
+const { verify_lock_disk_consistency } = require('../lock/verify')
 const { find_project_root, lock_root, skills_dir, skill_install_dir } = require('../config/paths')
 const { print_help, print_info, print_json, print_warn, code } = require('../ui/output')
 const { red, green, cyan, bold } = require('../ui/colors')
@@ -248,6 +249,23 @@ const run = (args) => catch_errors('Diff failed', async () => {
 	const base_dir = skills_dir(is_global, project_root)
 	const skill_dir = skill_install_dir(base_dir, repo)
 
+	// Drift (lock-vs-disk version mismatch) does NOT block diff — diff is the
+	// diagnostic tool a user reaches for precisely when things have diverged,
+	// and the obvious "remediation" (install --fresh) would destroy the local
+	// content they're trying to inspect. We probe drift only to warn the user
+	// that the "base" shown is the lock-recorded base (not the disk version's
+	// base). Skipped in --remote mode, which reads nothing from disk.
+	const drift = mode === 'remote'
+		? null
+		: (await verify_lock_disk_consistency(lock_entry, skill_dir))[1]
+	const has_drift = drift && !drift.ok
+	if (has_drift && !args.flags.json) {
+		print_warn(
+			`${skill_name} has drift: lock ${drift.expected}, disk ${drift.actual || 'none'}. ` +
+			`Diff is shown against the lock-recorded base (${lock_entry.version}).`
+		)
+	}
+
 	// Always need base files — keep full clone response for content diffs
 	const [base_err, base_clone] = await repos_api.clone(owner, repo, null, { commit: lock_entry.base_commit })
 	if (base_err) throw e('Failed to fetch base files', base_err)
@@ -266,7 +284,7 @@ const run = (args) => catch_errors('Diff failed', async () => {
 		}
 
 		if (args.flags.json) {
-			print_json({ data: { mode, report } })
+			print_json({ data: { mode, report, drift: has_drift ? { reason: drift.reason, lock_version: drift.expected, disk_version: drift.actual } : null } })
 		} else {
 			print_file_table(classified)
 			print_report_diffs(report)
@@ -319,7 +337,7 @@ const run = (args) => catch_errors('Diff failed', async () => {
 	}
 
 	if (args.flags.json) {
-		print_json({ data: { mode, report } })
+		print_json({ data: { mode, report, drift: has_drift ? { reason: drift.reason, lock_version: drift.expected, disk_version: drift.actual } : null } })
 	} else {
 		print_file_table(classified)
 		print_report_diffs(report)

package/src/commands/list.js

@@ -1,13 +1,14 @@
 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 { 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')
 const { AGENTS } = require('../agents/registry')
 const { resolve_agents } = require('../agents/detector')
 const { get_skills_enabled_map } = require('../agents/status')
-const { print_help, print_table, print_json, print_info } = require('../ui/output')
-const { green, yellow } = require('../ui/colors')
+const { print_help, print_table, print_json, print_info, print_warn, print_hint, code } = require('../ui/output')
+const { green, yellow, red } = require('../ui/colors')
 const { exit_with_error } = require('../utils/errors')
 const { EXIT_CODES, SKILL_JSON, SKILL_TYPES } = require('../constants')
 
@@ -75,17 +76,30 @@ 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.
+	const drift_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 (args.flags.json) {
 		const skills_map = {}
 		for (const [name, data] of managed_entries) {
 			const short = name.split('/')[1]
 			const dir = skill_install_dir(base_dir, short)
 			const [, exists] = await file_exists(dir)
-			const status = exists ? 'installed' : 'missing'
+			const drift = drift_by_skill[name]
+			const status = drift ? 'drift' : (exists ? 'installed' : 'missing')
 			const source = data.requested_by?.includes('__root__') ? 'direct' : 'dep'
 			const type = await resolve_type(name, data)
 			const enabled = enabled_map?.get(short) ?? true
-			skills_map[name] = { version: data.version, type, source, status, enabled }
+			const entry = { version: data.version, type, source, status, enabled }
+			if (drift) entry.drift = { reason: drift.reason, lock_version: drift.expected, disk_version: drift.actual }
+			skills_map[name] = entry
 		}
 		const external = external_skills.map(s => ({ name: s.name, description: s.description || '' }))
 		const agent_orphan_list = orphan_skills.map(s => ({
@@ -102,13 +116,16 @@ const run = (args) => catch_errors('List failed', async () => {
 		const short = name.split('/')[1]
 		const dir = skill_install_dir(base_dir, short)
 		const [, exists] = await file_exists(dir)
-		const status = exists ? 'installed' : 'missing'
+		const drift = drift_by_skill[name]
+		const status_label = drift
+			? red(`drift (disk ${drift.actual || 'none'})`)
+			: (exists ? 'installed' : 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
 		const enabled = enabled_map?.get(short) ?? true
 		const enabled_label = enabled ? green('enabled') : yellow('disabled')
-		rows.push([display_name, data.version, source, status, enabled_label])
+		rows.push([display_name, data.version, source, status_label, enabled_label])
 	}
 
 	for (const s of external_skills) {
@@ -121,6 +138,13 @@ 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
+	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.`)
+	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
 module.exports = { run }

package/src/commands/publish.js

@@ -13,6 +13,7 @@ const { find_project_root } = require('../config/paths')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
 const { write_lock, update_lock_skills } = require('../lock/writer')
 const { hash_directory } = require('../lock/integrity')
+const { verify_lock_disk_consistency } = require('../lock/verify')
 const { validate_skill_md } = require('../validation/skill_md_rules')
 const { validate_skill_json } = require('../validation/skill_json_rules')
 const { validate_cross } = require('../validation/cross_rules')
@@ -261,6 +262,7 @@ const run = (args) => catch_errors('Publish failed', async () => {
 
 	// Update lock file: set base_commit and base_integrity to new values
 	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}`
@@ -281,6 +283,7 @@ const run = (args) => catch_errors('Publish failed', async () => {
 			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,
@@ -294,6 +297,21 @@ const run = (args) => catch_errors('Publish failed', async () => {
 			}
 			const updated_skills = update_lock_skills(lock_data, { [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
+	// disk skill.json (the version we just published). The push has already
+	// succeeded server-side, so a mismatch here is a structural bug we want
+	// to surface immediately rather than silently bake into the lock.
+	if (post_publish_entry) {
+		const [, verify_result] = await verify_lock_disk_consistency(post_publish_entry, dir)
+		if (verify_result && !verify_result.ok) {
+			print_warn(
+				`Publish succeeded but lock and disk disagree (lock ${verify_result.expected}, disk ${verify_result.actual || 'none'}). ` +
+				`Run ${code(`happyskills install ${full_name} --fresh`)} to resync.`
+			)
 		}
 	}
 

package/src/commands/pull.js

@@ -14,6 +14,7 @@ const { satisfies } = require('../utils/semver')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
 const { write_lock, update_lock_skills } = require('../lock/writer')
 const { hash_directory } = require('../lock/integrity')
+const { verify_lock_disk_consistency } = require('../lock/verify')
 const { find_project_root, lock_root, skills_dir, skill_install_dir } = require('../config/paths')
 const { ensure_dir } = require('../utils/fs')
 const { create_spinner } = require('../ui/spinner')
@@ -211,6 +212,17 @@ const run = (args) => catch_errors('Pull failed', async () => {
 		const [wl_err] = await write_lock(lock_root(is_global, project_root), merged_skills)
 		if (wl_err) { spinner.fail('Failed to write lock file'); throw wl_err[0] }
 
+		// Post-write verification — see installer.js for the rationale.
+		const [, ff_verify] = await verify_lock_disk_consistency(updated_entry, skill_dir)
+		if (ff_verify && !ff_verify.ok) {
+			spinner.fail(`Pull verification failed: ${skill_name}`)
+			throw new Error(
+				`Pull of ${skill_name} completed but lock and disk disagree ` +
+				`(lock ${ff_verify.expected}, disk ${ff_verify.actual || 'none'}). ` +
+				`Re-run with happyskills install ${skill_name} --fresh to restore.`
+			)
+		}
+
 		spinner.stop()
 		if (args.flags.json) {
 			print_json({ data: { status: 'fast_forward', skill: skill_name, version: cmp_data.head_version } })
@@ -451,11 +463,26 @@ const run = (args) => catch_errors('Pull failed', async () => {
 	const [wl_err] = await write_lock(lock_root(is_global, project_root), merged_skills)
 	if (wl_err) { spinner.fail('Failed to write lock file'); throw wl_err[0] }
 
+	// Post-merge verification — surface any disagreement between the new lock
+	// entry and the on-disk skill.json. A 3-way merge can legitimately resolve
+	// the version field to either side, so this is a warning, not a hard fail
+	// (the user already has conflict_files to review). For fast-forward see
+	// the matching block above which throws instead.
+	const [, merge_verify] = await verify_lock_disk_consistency(updated_entry, skill_dir)
+	const post_merge_drift = merge_verify && !merge_verify.ok ? merge_verify : null
+
 	spinner.stop()
 
 	if (args.flags.json) {
 		const status = conflict_files.length > 0 ? 'conflicts' : 'merged'
 		const output = { status, report, conflict_files, json_conflicts }
+		if (post_merge_drift) {
+			output.drift = {
+				reason: post_merge_drift.reason,
+				lock_version: post_merge_drift.expected,
+				disk_version: post_merge_drift.actual
+			}
+		}
 		if (full_report) output.resolution_steps = build_resolution_steps(report, json_conflicts)
 		print_json({ data: output })
 	} else {
@@ -484,6 +511,10 @@ const run = (args) => catch_errors('Pull failed', async () => {
 				console.error(`  - ${f}`)
 			}
 		}
+		if (post_merge_drift) {
+			print_warn(`Lock and on-disk skill.json disagree after merge: lock ${post_merge_drift.expected}, disk ${post_merge_drift.actual || 'none'}.`)
+			print_hint(`Update skill.json's version to match the lock, or run ${code(`happyskills install ${skill_name} --fresh`)} to re-sync.`)
+		}
 	}
 
 	// 7. Dependency reconciliation

package/src/commands/status.js

@@ -1,8 +1,9 @@
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
 const { detect_status } = require('../merge/detector')
+const { verify_lock_disk_consistency, describe_drift } = require('../lock/verify')
 const repos_api = require('../api/repos')
-const { print_help, print_info, print_json } = require('../ui/output')
+const { print_help, print_info, print_json, print_warn, print_hint, code } = require('../ui/output')
 const { exit_with_error, UsageError } = require('../utils/errors')
 const { find_project_root, lock_root, skills_dir, skill_install_dir } = require('../config/paths')
 const { EXIT_CODES } = require('../constants')
@@ -25,7 +26,11 @@ Examples:
   happyskills st acme/deploy-aws
   happyskills status --json`
 
-const classify = (local_modified, remote_updated, has_conflicts) => {
+// Drift outranks every other status: when the lock and the on-disk skill.json
+// disagree about what's installed, every other comparison (modified/outdated/
+// diverged/conflicts) is computed against an untrustworthy baseline.
+const classify = (drift, local_modified, remote_updated, has_conflicts) => {
+	if (drift && !drift.ok) return 'drift'
 	if (has_conflicts) return 'conflicts'
 	if (local_modified && remote_updated) return 'diverged'
 	if (local_modified) return 'modified'
@@ -69,15 +74,20 @@ const run = (args) => catch_errors('Status failed', async () => {
 
 	const base_dir = skills_dir(is_global, project_root)
 
-	// Detect local modifications for all skills in parallel
-	const detections = await Promise.all(entries.map(([name, data]) => {
-		if (!data) return { name, data, det: null }
+	// Detect drift (lock-vs-disk version mismatch) and local modifications in parallel.
+	// The drift probe is cheap (one skill.json read + version compare); detect_status
+	// is the heavier integrity check. Running both lets us distinguish "user edited
+	// content" from "structural baseline broken".
+	const detections = await Promise.all(entries.map(async ([name, data]) => {
+		if (!data) return { name, data, det: null, drift: null }
 		const short_name = name.split('/')[1] || name
 		const dir = skill_install_dir(base_dir, short_name)
-		return detect_status(data, dir, { skill_name: name, project_root, is_global }).then(([, det]) => ({ name, data, det }))
+		const [, drift] = await verify_lock_disk_consistency(data, dir)
+		const [, det] = await detect_status(data, dir, { skill_name: name, project_root, is_global })
+		return { name, data, det, drift }
 	}))
 
-	const results = detections.map(({ name, data, det }) => {
+	const results = detections.map(({ name, data, det, drift }) => {
 		if (!data) return { skill: name, status: 'not_found', local_modified: false, remote_updated: false }
 		const has_conflicts = (data.conflict_files || []).length > 0
 		return {
@@ -91,7 +101,10 @@ const run = (args) => catch_errors('Status failed', async () => {
 			remote_version: null,
 			remote_commit: null,
 			conflict_files: data.conflict_files || [],
-			status: has_conflicts ? 'conflicts' : 'clean'
+			drift: drift && !drift.ok
+				? { reason: drift.reason, lock_version: drift.expected, disk_version: drift.actual }
+				: null,
+			status: drift && !drift.ok ? 'drift' : (has_conflicts ? 'conflicts' : 'clean')
 		}
 	})
 
@@ -113,10 +126,12 @@ const run = (args) => catch_errors('Status failed', async () => {
 		}
 	}
 
-	// Classify each result
+	// Classify each result. The drift field is the canonical structural-baseline
+	// signal; pass it to classify so it can outrank everything else.
 	for (const r of results) {
 		if (r.status !== 'not_found') {
-			r.status = classify(r.local_modified, r.remote_updated, r.conflict_files.length > 0)
+			const drift_check = r.drift ? { ok: false } : { ok: true }
+			r.status = classify(drift_check, r.local_modified, r.remote_updated, r.conflict_files.length > 0)
 		}
 	}
 
@@ -135,12 +150,18 @@ const run = (args) => catch_errors('Status failed', async () => {
 		skill: r.skill,
 		base: r.base_version || '?',
 		remote: r.remote_version || '?',
-		status: r.status === 'conflicts' ? 'conflicts (unresolved merge conflicts)'
-			: r.status === 'diverged' ? 'diverged (local + remote changes)'
-				: r.status === 'modified' ? 'modified (local changes)'
-					: r.status === 'outdated' ? 'outdated (remote changes)'
-						: r.status === 'not_found' ? 'not found'
-							: 'clean'
+		status: r.status === 'drift' ? describe_drift({
+			ok: false,
+			reason: r.drift?.reason,
+			expected: r.drift?.lock_version,
+			actual: r.drift?.disk_version
+		})
+			: r.status === 'conflicts' ? 'conflicts (unresolved merge conflicts)'
+				: r.status === 'diverged' ? 'diverged (local + remote changes)'
+					: r.status === 'modified' ? 'modified (local changes)'
+						: r.status === 'outdated' ? 'outdated (remote changes)'
+							: r.status === 'not_found' ? 'not found'
+								: 'clean'
 	}))
 
 	const w_skill = Math.max(col_skill.length, ...rows.map(r => r.skill.length))
@@ -153,6 +174,14 @@ const run = (args) => catch_errors('Status failed', async () => {
 	for (const r of rows) {
 		console.log(`${pad(r.skill, w_skill)}  ${pad(r.base, w_base)}  ${pad(r.remote, w_remote)}  ${r.status}`)
 	}
+
+	const drifted = results.filter(r => r.status === 'drift')
+	if (drifted.length > 0) {
+		console.log()
+		print_warn(`${drifted.length} skill(s) drifted: lock and on-disk skill.json disagree.`)
+		print_hint(`Restore install record: ${code('happyskills install <skill> --fresh')}`)
+		print_hint(`Or accept the on-disk version: bump the lock by reinstalling at the disk version.`)
+	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
 module.exports = { run }

package/src/commands/update.js

@@ -3,6 +3,7 @@ const { install } = require('../engine/installer')
 const { read_lock, get_all_locked_skills, get_via } = require('../lock/reader')
 const { read_manifest } = require('../manifest/reader')
 const { detect_status } = require('../merge/detector')
+const { verify_lock_disk_consistency } = require('../lock/verify')
 const repos_api = require('../api/repos')
 const { print_help, print_table, print_json, print_info, print_success, print_warn, print_hint, code } = require('../ui/output')
 const { green, yellow, red } = require('../ui/colors')
@@ -140,18 +141,27 @@ const run = (args) => catch_errors('Update failed', async () => {
 	} else {
 		spinner?.succeed('Checked for updates')
 
-		// Read installed manifests in parallel for dependency-drift detection
+		// Read installed manifests + drift in parallel. Drift detection here
+		// matches the read-side surfacing in status/check — update should not
+		// silently treat a drifted skill as "up-to-date" or auto-overwrite it.
 		const manifest_map = {}
-		await Promise.all(candidates.map(async ([name]) => {
+		const drift_by_skill = {}
+		await Promise.all(candidates.map(async ([name, data]) => {
 			const short_name = name.split('/')[1] || name
 			const dir = skill_install_dir(base_dir, short_name)
 			const [, manifest] = await read_manifest(dir)
 			if (manifest) manifest_map[name] = manifest
+			const [, drift] = await verify_lock_disk_consistency(data, dir)
+			if (drift && !drift.ok) drift_by_skill[name] = drift
 		}))
 
 		for (const [name, data] of candidates) {
 			const info = batch_data?.results?.[name]
-			if (info?.access_denied) {
+			const drift = drift_by_skill[name]
+			if (drift) {
+				// Drift outranks every other status — fix the baseline before updating.
+				results.push({ skill: name, installed: data.version, latest: info?.latest_version || '-', status: 'drift', drift: { reason: drift.reason, lock_version: drift.expected, disk_version: drift.actual } })
+			} else if (info?.access_denied) {
 				results.push({ skill: name, installed: data.version, latest: '-', status: 'no-access' })
 			} else if (!info || !info.latest_version) {
 				results.push({ skill: name, installed: data.version, latest: '-', status: 'unknown' })
@@ -171,6 +181,7 @@ const run = (args) => catch_errors('Update failed', async () => {
 
 	const outdated = results.filter(r => r.status === 'outdated')
 	const up_to_date = results.filter(r => r.status === 'up-to-date')
+	const drifted = results.filter(r => r.status === 'drift')
 
 	// Verify and repair symlinks (even when nothing is outdated)
 	const [, agents_data] = await resolve_agents(args.flags.agents)
@@ -202,14 +213,20 @@ const run = (args) => catch_errors('Update failed', async () => {
 	// If nothing to update, report and exit
 	if (outdated.length === 0) {
 		if (args.flags.json) {
-			print_json({ data: { results, outdated_count: 0, up_to_date_count: up_to_date.length, updated: [], already_up_to_date: up_to_date.map(r => ({ skill: r.skill, version: r.installed })), symlink_repairs, errors: [] } })
+			print_json({ data: { results, outdated_count: 0, up_to_date_count: up_to_date.length, drift_count: drifted.length, updated: [], already_up_to_date: up_to_date.map(r => ({ skill: r.skill, version: r.installed })), symlink_repairs, errors: [] } })
 			return
 		}
 		print_table(['Skill', 'Installed', 'Latest', 'Status'], results.map(r => [
-			r.skill, r.installed, r.latest, green(r.status)
+			r.skill, r.installed, r.latest, r.status === 'drift' ? red('drift') : green(r.status)
 		]))
 		console.log()
-		if (symlink_repairs.length > 0) {
+		if (drifted.length > 0) {
+			print_warn(`${drifted.length} skill(s) drifted: lock and on-disk skill.json disagree.`)
+			for (const r of drifted) {
+				console.error(`  - ${r.skill} (lock ${r.drift?.lock_version}, disk ${r.drift?.disk_version || 'none'})`)
+			}
+			print_hint(`Restore each one with ${code('happyskills install <skill> --fresh')} before updating.`)
+		} else if (symlink_repairs.length > 0) {
 			print_success(`All skills are up to date. Repaired ${symlink_repairs.length} symlink(s).`)
 		} else {
 			print_success('All skills are up to date.')
@@ -219,11 +236,18 @@ const run = (args) => catch_errors('Update failed', async () => {
 
 	// Show results table (non-json)
 	if (!args.flags.json) {
-		const status_colors = { 'up-to-date': green, 'outdated': yellow, 'no-access': yellow, 'error': red, 'unknown': (s) => s }
+		const status_colors = { 'up-to-date': green, 'outdated': yellow, 'drift': red, 'no-access': yellow, 'error': red, 'unknown': (s) => s }
 		print_table(['Skill', 'Installed', 'Latest', 'Status'], results.map(r => [
 			r.skill, r.installed, r.latest, (status_colors[r.status] || ((s) => s))(r.status)
 		]))
 		console.log()
+		if (drifted.length > 0) {
+			print_warn(`${drifted.length} skill(s) drifted — these will be skipped:`)
+			for (const r of drifted) {
+				console.error(`  - ${r.skill} (lock ${r.drift?.lock_version}, disk ${r.drift?.disk_version || 'none'})`)
+			}
+			print_hint(`Restore each one with ${code('happyskills install <skill> --fresh')} to update them.`)
+		}
 		print_info(`${outdated.length} skill(s) can be updated.`)
 	}
 
@@ -281,6 +305,7 @@ const run = (args) => catch_errors('Update failed', async () => {
 				results,
 				outdated_count: outdated.length,
 				up_to_date_count: up_to_date.length,
+				drift_count: drifted.length,
 				updated,
 				skipped,
 				already_up_to_date: up_to_date.map(r => ({ skill: r.skill, version: r.installed })),

package/src/engine/installer.js

@@ -8,6 +8,7 @@ const { check_system_dependencies } = require('./system_deps')
 const { hash_directory, verify_integrity } = require('../lock/integrity')
 const { read_lock, get_locked_skill } = require('../lock/reader')
 const { write_lock, update_lock_skills } = require('../lock/writer')
+const { verify_lock_disk_consistency } = require('../lock/verify')
 const { skills_dir, tmp_dir, skill_install_dir, lock_root } = require('../config/paths')
 const { ensure_dir, remove_dir, file_exists, read_json } = require('../utils/fs')
 const { SKILL_JSON, SKILL_TYPES } = require('../constants')
@@ -256,6 +257,24 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 		const [lock_errors] = await write_lock(lock_dir, new_skills)
 		if (lock_errors) { spinner.fail('Failed to write lock file'); throw e('Lock write failed', lock_errors) }
 
+		// Post-write verification: confirm every newly-written lock entry agrees
+		// with the on-disk skill.json. Catches any drift the install pipeline
+		// would have created (interrupted rename, resolver-vs-disk version skew,
+		// extractor regression, etc.) before declaring success.
+		for (const { pkg } of downloaded) {
+			const name = pkg.skill.split('/')[1]
+			const final_dir = skill_install_dir(base_dir, name)
+			const [, verify_result] = await verify_lock_disk_consistency(updates[pkg.skill], final_dir)
+			if (verify_result && !verify_result.ok) {
+				spinner.fail(`Install verification failed: ${pkg.skill}`)
+				throw new Error(
+					`Install of ${pkg.skill} completed but lock and disk disagree ` +
+					`(lock ${verify_result.expected}, disk ${verify_result.actual || 'none'}). ` +
+					`Re-run with --fresh to retry.`
+				)
+			}
+		}
+
 		spinner.succeed(`Installed ${packages_to_install.length} package(s)`)
 
 		const linked_count = downloaded.length - disabled_skills.size

package/src/integration/drift.test.js

@@ -0,0 +1,300 @@
+'use strict'
+/**
+ * Regression tests for the lock-vs-disk drift bug class.
+ *
+ * Background: an interrupted `update`/`install`, a manual edit to skill.json,
+ * or a partial refresh can leave the lock entry's `version` field disagreeing
+ * with the on-disk skill.json's `version`. Before this fix:
+ *   - `check` reported `up-to-date` (it never read the disk)
+ *   - `status` reported `modified (local changes)` (it noticed the integrity
+ *     hash differed but mislabeled the cause as user edits)
+ *   - `list` reported the lock's version as the installed version (lying)
+ *   - `diff` used the lock's `base_commit` as a comparison baseline that no
+ *     longer matched what was on disk (incoherent diff)
+ *
+ * Note on `diff`: an earlier fix hard-blocked `diff` on drift. That was wrong
+ * — diff is the diagnostic tool a user reaches for *because* of drift, and
+ * the suggested "install --fresh" remediation would destroy the local
+ * content. The current behavior is to warn and proceed.
+ *   - `update` could decide a drifted skill was up-to-date and skip it
+ *
+ * These tests reconstruct the exact linwong scenario that surfaced the bug
+ * (lock 0.4.0, disk 0.3.0) and assert every drift-aware command surfaces it
+ * via the structured `drift` field. If any of these break, the bug class is
+ * back.
+ */
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const { spawnSync } = require('child_process')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+const CLI = path.resolve(__dirname, '../../bin/happyskills.js')
+const NODE = process.execPath
+
+const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'happyskills-drift-test-'))
+
+const run = (args, opts) => {
+	const result = spawnSync(NODE, [CLI, ...args], {
+		env: {
+			...process.env,
+			NO_COLOR: '1',
+			HAPPYSKILLS_API_URL: 'http://localhost:0',
+			...(opts?.env || {})
+		},
+		encoding: 'utf-8',
+		timeout: 10000,
+		cwd: opts?.cwd
+	})
+	return { stdout: result.stdout || '', stderr: result.stderr || '', code: result.status }
+}
+
+const parse_json = (stdout, label) => {
+	try { return JSON.parse(stdout) }
+	catch { assert.fail(`${label}: stdout is not valid JSON:\n${stdout}`) }
+}
+
+/**
+ * Scaffold a project with an explicitly drifted skill: lock entry says one
+ * version, on-disk skill.json says another. Mirrors the linwong bug exactly.
+ *
+ * @param {Array<{full, short, lock_version, disk_version, integrity?}>} skills
+ */
+const scaffold_drifted = (skills) => {
+	const root = make_tmp()
+	const lock_skills = {}
+
+	for (const s of skills) {
+		const skill_dir = path.join(root, '.agents', 'skills', s.short)
+		fs.mkdirSync(skill_dir, { recursive: true })
+		fs.writeFileSync(
+			path.join(skill_dir, 'SKILL.md'),
+			`---\nname: ${s.short}\ndescription: test skill for drift regression\n---\nTest body\n`
+		)
+		// disk_version is what skill.json claims — may differ from lock
+		fs.writeFileSync(
+			path.join(skill_dir, 'skill.json'),
+			JSON.stringify({
+				name: s.short,
+				version: s.disk_version,
+				type: 'skill',
+				description: 'test skill for drift regression'
+			}, null, '\t')
+		)
+
+		lock_skills[s.full] = {
+			version: s.lock_version,
+			type: 'skill',
+			ref: `refs/tags/v${s.lock_version}`,
+			commit: 'lockcommit',
+			integrity: s.integrity || null,
+			base_commit: 'lockcommit',
+			base_integrity: s.integrity || null,
+			requested_by: ['__root__'],
+			dependencies: {}
+		}
+	}
+
+	fs.writeFileSync(path.join(root, 'skills-lock.json'), JSON.stringify({
+		lockVersion: 2,
+		generatedAt: new Date().toISOString(),
+		skills: lock_skills
+	}, null, '\t'))
+
+	return { root, cleanup: () => fs.rmSync(root, { recursive: true, force: true }) }
+}
+
+// ─── status ───────────────────────────────────────────────────────────────────
+
+describe('status — drift detection', () => {
+	it('reports drift when lock version differs from disk skill.json version (the linwong bug)', () => {
+		const { root, cleanup } = scaffold_drifted([
+			{ full: 'happyskillsai/happyskills-design', short: 'happyskills-design', lock_version: '0.4.0', disk_version: '0.3.0' }
+		])
+		try {
+			const { code, stdout } = run(['status', '--json'], { cwd: root })
+			assert.strictEqual(code, 0, 'status should exit 0')
+			const out = parse_json(stdout, 'status --json')
+			const result = out.data.results.find(r => r.skill === 'happyskillsai/happyskills-design')
+			assert.ok(result, 'result for the drifted skill must be present')
+			assert.strictEqual(result.status, 'drift', 'status must be reported as drift, not modified or clean')
+			assert.deepEqual(result.drift, {
+				reason: 'version_mismatch',
+				lock_version: '0.4.0',
+				disk_version: '0.3.0'
+			})
+		} finally { cleanup() }
+	})
+
+	it('drift outranks modified — does not mislabel structural drift as local edits', () => {
+		// Critical regression: previously reported as "modified (local changes)"
+		const { root, cleanup } = scaffold_drifted([
+			{ full: 'acme/foo', short: 'foo', lock_version: '2.0.0', disk_version: '1.0.0' }
+		])
+		try {
+			const { code, stdout } = run(['status', '--json'], { cwd: root })
+			assert.strictEqual(code, 0)
+			const out = parse_json(stdout, 'status --json')
+			const result = out.data.results[0]
+			assert.strictEqual(result.status, 'drift', 'must be drift, not modified')
+			assert.notStrictEqual(result.status, 'modified', 'modified would mislead — this is structural drift, not user edits')
+		} finally { cleanup() }
+	})
+
+	it('reports clean when lock and disk agree', () => {
+		const { root, cleanup } = scaffold_drifted([
+			{ full: 'acme/agree', short: 'agree', lock_version: '1.0.0', disk_version: '1.0.0' }
+		])
+		try {
+			const { code, stdout } = run(['status', '--json'], { cwd: root })
+			assert.strictEqual(code, 0)
+			const out = parse_json(stdout, 'status --json')
+			const result = out.data.results[0]
+			assert.strictEqual(result.drift, null)
+			assert.notStrictEqual(result.status, 'drift')
+		} finally { cleanup() }
+	})
+
+	it('detects missing_skill_json drift when skill.json is gone', () => {
+		const { root, cleanup } = scaffold_drifted([
+			{ full: 'acme/headless', short: 'headless', lock_version: '1.0.0', disk_version: '1.0.0' }
+		])
+		try {
+			fs.unlinkSync(path.join(root, '.agents', 'skills', 'headless', 'skill.json'))
+			const { code, stdout } = run(['status', '--json'], { cwd: root })
+			assert.strictEqual(code, 0)
+			const out = parse_json(stdout, 'status --json')
+			const result = out.data.results[0]
+			assert.strictEqual(result.status, 'drift')
+			assert.strictEqual(result.drift.reason, 'missing_skill_json')
+		} finally { cleanup() }
+	})
+
+	it('human output includes the drift cell with both versions', () => {
+		const { root, cleanup } = scaffold_drifted([
+			{ full: 'acme/show', short: 'show', lock_version: '0.4.0', disk_version: '0.3.0' }
+		])
+		try {
+			const { code, stdout } = run(['status'], { cwd: root })
+			assert.strictEqual(code, 0)
+			assert.ok(stdout.includes('drift'), 'status table must contain "drift"')
+			assert.ok(stdout.includes('0.4.0'), 'must show lock version')
+			assert.ok(stdout.includes('0.3.0'), 'must show disk version')
+		} finally { cleanup() }
+	})
+})
+
+// ─── check ────────────────────────────────────────────────────────────────────
+
+describe('check — drift detection', () => {
+	it('reports drift even when the registry API is unreachable', () => {
+		// HAPPYSKILLS_API_URL=http://localhost:0 makes the API call fail.
+		// Drift detection is purely local — it must still surface.
+		const { root, cleanup } = scaffold_drifted([
+			{ full: 'acme/local-only', short: 'local-only', lock_version: '0.4.0', disk_version: '0.3.0' }
+		])
+		try {
+			const { code, stdout } = run(['check', '--json'], { cwd: root })
+			assert.strictEqual(code, 0)
+			const out = parse_json(stdout, 'check --json')
+			const result = out.data.results.find(r => r.skill === 'acme/local-only')
+			assert.ok(result, 'result must be present even with API down')
+			assert.strictEqual(result.status, 'drift')
+			assert.deepEqual(result.drift, {
+				reason: 'version_mismatch',
+				lock_version: '0.4.0',
+				disk_version: '0.3.0'
+			})
+		} finally { cleanup() }
+	})
+
+	it('drift_count appears in the JSON summary', () => {
+		const { root, cleanup } = scaffold_drifted([
+			{ full: 'acme/one', short: 'one', lock_version: '1.0.0', disk_version: '0.9.0' },
+			{ full: 'acme/two', short: 'two', lock_version: '2.0.0', disk_version: '1.0.0' }
+		])
+		try {
+			const { code, stdout } = run(['check', '--json'], { cwd: root })
+			assert.strictEqual(code, 0)
+			const out = parse_json(stdout, 'check --json')
+			assert.strictEqual(out.data.drift_count, 2)
+		} finally { cleanup() }
+	})
+
+	it('drift overrides up-to-date — drift cannot be silently masked', () => {
+		const { root, cleanup } = scaffold_drifted([
+			{ full: 'acme/silent', short: 'silent', lock_version: '0.4.0', disk_version: '0.3.0' }
+		])
+		try {
+			const { code, stdout } = run(['check', '--json'], { cwd: root })
+			assert.strictEqual(code, 0)
+			const out = parse_json(stdout, 'check --json')
+			const result = out.data.results[0]
+			assert.notStrictEqual(result.status, 'up-to-date', 'must not silently report up-to-date when drifted')
+			assert.strictEqual(result.status, 'drift')
+		} finally { cleanup() }
+	})
+})
+
+// ─── list ─────────────────────────────────────────────────────────────────────
+
+describe('list — drift surfacing', () => {
+	it('list --json marks drifted skills with status "drift" and a drift object', () => {
+		const { root, cleanup } = scaffold_drifted([
+			{ full: 'acme/drifted', short: 'drifted', lock_version: '0.4.0', disk_version: '0.3.0' },
+			{ full: 'acme/clean', short: 'clean', lock_version: '1.0.0', disk_version: '1.0.0' }
+		])
+		try {
+			const { code, stdout } = run(['list', '--json'], { cwd: root })
+			assert.strictEqual(code, 0)
+			const out = parse_json(stdout, 'list --json')
+			assert.strictEqual(out.data.skills['acme/drifted'].status, 'drift')
+			assert.deepEqual(out.data.skills['acme/drifted'].drift, {
+				reason: 'version_mismatch',
+				lock_version: '0.4.0',
+				disk_version: '0.3.0'
+			})
+			assert.strictEqual(out.data.skills['acme/clean'].status, 'installed')
+			assert.strictEqual(out.data.skills['acme/clean'].drift, undefined)
+		} finally { cleanup() }
+	})
+})
+
+// ─── diff ─────────────────────────────────────────────────────────────────────
+
+describe('diff — drift does not block', () => {
+	it('diff proceeds past the drift check (no UsageError) and warns the user', () => {
+		// Drift must not block diff: diff is the diagnostic tool for this case,
+		// and "install --fresh" would destroy the local content. We assert that
+		// the command moves past the drift gate — it will then fail trying to
+		// reach the fake API URL, but exit code 2 (UsageError) means the old
+		// pre-block is back.
+		const { root, cleanup } = scaffold_drifted([
+			{ full: 'acme/cant-diff', short: 'cant-diff', lock_version: '0.4.0', disk_version: '0.3.0' }
+		])
+		try {
+			const { code, stderr } = run(['diff', 'acme/cant-diff'], { cwd: root })
+			assert.notStrictEqual(code, 2, 'must not exit with the old drift UsageError')
+			assert.ok(
+				stderr.toLowerCase().includes('drift') && stderr.includes('0.4.0') && stderr.includes('0.3.0'),
+				'should warn about drift with both versions'
+			)
+			assert.ok(
+				!/before diffing/i.test(stderr),
+				'must not tell the user to fix drift before diffing'
+			)
+		} finally { cleanup() }
+	})
+
+	it('diff --remote skips the drift probe entirely (drift is irrelevant when no disk is read)', () => {
+		const { root, cleanup } = scaffold_drifted([
+			{ full: 'acme/cant-diff', short: 'cant-diff', lock_version: '0.4.0', disk_version: '0.3.0' }
+		])
+		try {
+			const { code, stderr } = run(['diff', 'acme/cant-diff', '--remote'], { cwd: root })
+			assert.notStrictEqual(code, 2, 'must not exit with the old drift UsageError')
+			assert.ok(!/drift/i.test(stderr), '--remote mode should not surface drift at all')
+		} finally { cleanup() }
+	})
+})

package/src/lock/verify.js

@@ -0,0 +1,48 @@
+const path = require('path')
+const { error: { catch_errors } } = require('puffy-core')
+const { read_json, file_exists } = require('../utils/fs')
+const { SKILL_JSON } = require('../constants')
+
+// Cheapest possible drift probe: read the on-disk skill.json and compare its
+// version field to the lock entry's version. Catches the most common class of
+// lock/disk drift (interrupted install, manual file edit, partial update)
+// without paying for a full directory hash.
+//
+// Result shapes:
+//   { ok: true }
+//   { ok: false, reason: 'missing_dir',         expected, actual: null }
+//   { ok: false, reason: 'missing_skill_json',  expected, actual: null }
+//   { ok: false, reason: 'version_mismatch',    expected, actual }
+const verify_lock_disk_consistency = (lock_entry, install_dir) => catch_errors('Failed to verify lock/disk consistency', async () => {
+	const expected = lock_entry?.version || null
+
+	// Nothing in the lock to check against — caller has nothing to verify.
+	if (!expected) return { ok: true }
+
+	const [, dir_exists] = await file_exists(install_dir)
+	if (!dir_exists) return { ok: false, reason: 'missing_dir', expected, actual: null }
+
+	const manifest_path = path.join(install_dir, SKILL_JSON)
+	const [, manifest_exists] = await file_exists(manifest_path)
+	if (!manifest_exists) return { ok: false, reason: 'missing_skill_json', expected, actual: null }
+
+	const [read_err, manifest] = await read_json(manifest_path)
+	if (read_err) return { ok: false, reason: 'missing_skill_json', expected, actual: null }
+
+	const actual = manifest?.version || null
+	if (actual !== expected) return { ok: false, reason: 'version_mismatch', expected, actual }
+
+	return { ok: true }
+})
+
+// Plain-language description of a drift result, suitable for the principal-facing
+// table cell (status column). Returns null when ok.
+const describe_drift = (verify_result) => {
+	if (!verify_result || verify_result.ok) return null
+	if (verify_result.reason === 'missing_dir') return `drift (lock ${verify_result.expected}, skill not on disk)`
+	if (verify_result.reason === 'missing_skill_json') return `drift (lock ${verify_result.expected}, no skill.json on disk)`
+	if (verify_result.reason === 'version_mismatch') return `drift (lock ${verify_result.expected}, disk ${verify_result.actual})`
+	return 'drift'
+}
+
+module.exports = { verify_lock_disk_consistency, describe_drift }

package/src/lock/verify.test.js

@@ -0,0 +1,137 @@
+'use strict'
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const os = require('os')
+const path = require('path')
+const fs = require('fs')
+
+const { verify_lock_disk_consistency, describe_drift } = require('./verify')
+
+const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-verify-test-'))
+const cleanup = (dir) => fs.rmSync(dir, { recursive: true, force: true })
+
+const write_skill_json = (dir, manifest) => {
+	fs.mkdirSync(dir, { recursive: true })
+	fs.writeFileSync(path.join(dir, 'skill.json'), JSON.stringify(manifest, null, '\t'))
+}
+
+describe('verify_lock_disk_consistency', () => {
+	it('returns ok when lock version matches disk version', async () => {
+		const dir = make_tmp()
+		try {
+			const install_dir = path.join(dir, 'my-skill')
+			write_skill_json(install_dir, { name: 'my-skill', version: '1.2.0' })
+			const [err, result] = await verify_lock_disk_consistency({ version: '1.2.0' }, install_dir)
+			assert.strictEqual(err, null)
+			assert.deepEqual(result, { ok: true })
+		} finally { cleanup(dir) }
+	})
+
+	it('detects version_mismatch when disk skill.json has a different version (the linwong bug)', async () => {
+		const dir = make_tmp()
+		try {
+			const install_dir = path.join(dir, 'happyskills-design')
+			write_skill_json(install_dir, { name: 'happyskills-design', version: '0.3.0' })
+			const [err, result] = await verify_lock_disk_consistency({ version: '0.4.0' }, install_dir)
+			assert.strictEqual(err, null)
+			assert.deepEqual(result, { ok: false, reason: 'version_mismatch', expected: '0.4.0', actual: '0.3.0' })
+		} finally { cleanup(dir) }
+	})
+
+	it('detects missing_dir when the install directory does not exist', async () => {
+		const dir = make_tmp()
+		try {
+			const install_dir = path.join(dir, 'never-installed')
+			const [err, result] = await verify_lock_disk_consistency({ version: '1.0.0' }, install_dir)
+			assert.strictEqual(err, null)
+			assert.deepEqual(result, { ok: false, reason: 'missing_dir', expected: '1.0.0', actual: null })
+		} finally { cleanup(dir) }
+	})
+
+	it('detects missing_skill_json when the directory exists but skill.json is gone', async () => {
+		const dir = make_tmp()
+		try {
+			const install_dir = path.join(dir, 'broken-skill')
+			fs.mkdirSync(install_dir)
+			fs.writeFileSync(path.join(install_dir, 'SKILL.md'), '# stub')
+			const [err, result] = await verify_lock_disk_consistency({ version: '1.0.0' }, install_dir)
+			assert.strictEqual(err, null)
+			assert.deepEqual(result, { ok: false, reason: 'missing_skill_json', expected: '1.0.0', actual: null })
+		} finally { cleanup(dir) }
+	})
+
+	it('detects missing_skill_json when skill.json is unreadable JSON', async () => {
+		const dir = make_tmp()
+		try {
+			const install_dir = path.join(dir, 'corrupt-skill')
+			fs.mkdirSync(install_dir)
+			fs.writeFileSync(path.join(install_dir, 'skill.json'), '{ this is not json')
+			const [err, result] = await verify_lock_disk_consistency({ version: '1.0.0' }, install_dir)
+			assert.strictEqual(err, null)
+			assert.deepEqual(result, { ok: false, reason: 'missing_skill_json', expected: '1.0.0', actual: null })
+		} finally { cleanup(dir) }
+	})
+
+	it('detects version_mismatch when disk skill.json has no version field', async () => {
+		const dir = make_tmp()
+		try {
+			const install_dir = path.join(dir, 'no-version')
+			write_skill_json(install_dir, { name: 'no-version' })
+			const [err, result] = await verify_lock_disk_consistency({ version: '1.0.0' }, install_dir)
+			assert.strictEqual(err, null)
+			assert.deepEqual(result, { ok: false, reason: 'version_mismatch', expected: '1.0.0', actual: null })
+		} finally { cleanup(dir) }
+	})
+
+	it('returns ok when lock entry has no version (nothing to verify against)', async () => {
+		const dir = make_tmp()
+		try {
+			const install_dir = path.join(dir, 'unversioned')
+			const [err, result] = await verify_lock_disk_consistency({}, install_dir)
+			assert.strictEqual(err, null)
+			assert.deepEqual(result, { ok: true })
+		} finally { cleanup(dir) }
+	})
+
+	it('returns ok when lock entry is null (nothing to verify)', async () => {
+		const dir = make_tmp()
+		try {
+			const install_dir = path.join(dir, 'no-lock')
+			const [err, result] = await verify_lock_disk_consistency(null, install_dir)
+			assert.strictEqual(err, null)
+			assert.deepEqual(result, { ok: true })
+		} finally { cleanup(dir) }
+	})
+})
+
+describe('describe_drift', () => {
+	it('returns null for ok results', () => {
+		assert.strictEqual(describe_drift({ ok: true }), null)
+		assert.strictEqual(describe_drift(null), null)
+	})
+
+	it('describes version_mismatch with both versions', () => {
+		assert.strictEqual(
+			describe_drift({ ok: false, reason: 'version_mismatch', expected: '0.4.0', actual: '0.3.0' }),
+			'drift (lock 0.4.0, disk 0.3.0)'
+		)
+	})
+
+	it('describes missing_dir', () => {
+		assert.strictEqual(
+			describe_drift({ ok: false, reason: 'missing_dir', expected: '1.0.0', actual: null }),
+			'drift (lock 1.0.0, skill not on disk)'
+		)
+	})
+
+	it('describes missing_skill_json', () => {
+		assert.strictEqual(
+			describe_drift({ ok: false, reason: 'missing_skill_json', expected: '1.0.0', actual: null }),
+			'drift (lock 1.0.0, no skill.json on disk)'
+		)
+	})
+
+	it('falls back to bare drift for unknown reasons', () => {
+		assert.strictEqual(describe_drift({ ok: false, reason: 'something_new' }), 'drift')
+	})
+})