happyskills 0.48.0 → 0.49.0

package/src/integration/release.test.js

@@ -0,0 +1,183 @@
+'use strict'
+/**
+ * Integration tests for `happyskills release` — § 8.2.
+ *
+ * Focus: the failure-mode envelopes (drift, missing_version, missing_changelog
+ * entry) and the ahead-recognition path through --dry-run. The full happy-path
+ * publish requires a real registry and is covered by the existing publish
+ * pipeline tests; here we verify orchestration, snapshot capture/restore, and
+ * the structured next_step envelopes.
+ */
+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(), 'hs-release-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: 15000,
+		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}`) }
+}
+
+const scaffold = ({ full, short, lock_version, disk_version, changelog }) => {
+	const root = make_tmp()
+	const skill_dir = path.join(root, '.agents', 'skills', short)
+	fs.mkdirSync(skill_dir, { recursive: true })
+	fs.writeFileSync(
+		path.join(skill_dir, 'SKILL.md'),
+		`---\nname: ${short}\ndescription: release test skill for integration coverage\n---\n# ${short}\n\nbody\n`
+	)
+	fs.writeFileSync(
+		path.join(skill_dir, 'skill.json'),
+		JSON.stringify({
+			name: short,
+			version: disk_version,
+			type: 'skill',
+			description: 'release test skill for integration coverage',
+			keywords: ['testing']
+		}, null, '\t')
+	)
+	if (changelog) {
+		fs.writeFileSync(path.join(skill_dir, 'CHANGELOG.md'), changelog)
+	}
+	fs.writeFileSync(path.join(root, 'skills-lock.json'), JSON.stringify({
+		lockVersion: 2,
+		generatedAt: new Date().toISOString(),
+		skills: {
+			[full]: {
+				version: lock_version,
+				type: 'skill',
+				ref: `refs/tags/v${lock_version}`,
+				commit: 'lockcommit',
+				integrity: 'sha256-baseline',
+				base_commit: 'lockcommit',
+				base_integrity: 'sha256-baseline',
+				requested_by: ['__root__'],
+				dependencies: {}
+			}
+		}
+	}, null, '\t'))
+	return {
+		root,
+		skill_dir,
+		read_manifest: () => JSON.parse(fs.readFileSync(path.join(skill_dir, 'skill.json'), 'utf-8')),
+		read_lock: () => JSON.parse(fs.readFileSync(path.join(root, 'skills-lock.json'), 'utf-8')),
+		cleanup: () => fs.rmSync(root, { recursive: true, force: true })
+	}
+}
+
+describe('release — orchestration envelopes', () => {
+	it('blocks on regression drift and routes to reconcile', () => {
+		const ctx = scaffold({
+			full: 'acme/regressed', short: 'regressed',
+			lock_version: '1.0.0', disk_version: '0.9.0'
+		})
+		try {
+			const { code, stdout } = run(['release', 'regressed', '--workspace', 'acme', '--json'], { cwd: ctx.root })
+			assert.notStrictEqual(code, 0)
+			const env = parse_json(stdout, 'release regressed')
+			assert.strictEqual(env.error.code, 'DRIFT_DETECTED')
+			assert.strictEqual(env.next_step.action, 'reconcile_first')
+			assert.match(env.next_step.context.reconcile_command, /reconcile/)
+		} finally { ctx.cleanup() }
+	})
+
+	it('recognizes ahead via --dry-run and uses the disk version (no revert)', () => {
+		const ctx = scaffold({
+			full: 'acme/ahead-dry', short: 'ahead-dry',
+			lock_version: '0.3.2', disk_version: '0.3.3',
+			changelog: '# Changelog\n\n## [0.3.3]\n- added new thing\n'
+		})
+		try {
+			const { code, stdout } = run(['release', 'ahead-dry', '--workspace', 'acme', '--dry-run', '--json'], { cwd: ctx.root })
+			assert.strictEqual(code, 0, 'dry-run on ahead must succeed')
+			const env = parse_json(stdout, 'release ahead dry-run')
+			assert.strictEqual(env.data.dry_run, true)
+			assert.strictEqual(env.data.target_version, '0.3.3')
+			assert.strictEqual(env.data.ahead_recognized, true)
+			assert.strictEqual(env.data.bump_applied, false, 'ahead must NOT trigger a re-bump')
+			// Critical: skill.json must NOT have been mutated by release.
+			assert.strictEqual(ctx.read_manifest().version, '0.3.3')
+		} finally { ctx.cleanup() }
+	})
+
+	it('blocks with MISSING_VERSION on clean + --no-bump', () => {
+		const ctx = scaffold({
+			full: 'acme/clean', short: 'clean',
+			lock_version: '1.0.0', disk_version: '1.0.0'
+		})
+		try {
+			const { code, stdout } = run(['release', 'clean', '--workspace', 'acme', '--no-bump', '--json'], { cwd: ctx.root })
+			assert.notStrictEqual(code, 0)
+			const env = parse_json(stdout, 'release clean --no-bump')
+			assert.strictEqual(env.error.code, 'MISSING_VERSION')
+		} finally { ctx.cleanup() }
+	})
+
+	it('blocks with MISSING_CHANGELOG_ENTRY when bump succeeds but CHANGELOG lacks the new version', () => {
+		const ctx = scaffold({
+			full: 'acme/no-cl', short: 'no-cl',
+			lock_version: '1.0.0', disk_version: '1.0.0',
+			changelog: '# Changelog\n\n## [1.0.0]\n- initial\n'
+		})
+		try {
+			const { code, stdout } = run(['release', 'no-cl', '--bump', 'patch', '--workspace', 'acme', '--json'], { cwd: ctx.root })
+			assert.notStrictEqual(code, 0)
+			const env = parse_json(stdout, 'release no-cl')
+			assert.strictEqual(env.error.code, 'MISSING_CHANGELOG_ENTRY')
+			assert.strictEqual(env.next_step.action, 'provide_changelog')
+		} finally { ctx.cleanup() }
+	})
+
+	it('emits bump_disagreement when --bump value contradicts an already-ahead disk', () => {
+		const ctx = scaffold({
+			full: 'acme/disagree', short: 'disagree',
+			lock_version: '0.1.0', disk_version: '0.5.0'
+		})
+		try {
+			const { code, stdout } = run(['release', 'disagree', '--bump', 'patch', '--workspace', 'acme', '--json'], { cwd: ctx.root })
+			assert.notStrictEqual(code, 0)
+			const env = parse_json(stdout, 'release disagree')
+			assert.strictEqual(env.error.code, 'BUMP_DISAGREEMENT')
+			assert.strictEqual(env.next_step.action, 'resolve_bump_disagreement')
+			assert.strictEqual(env.next_step.context.disk_version, '0.5.0')
+		} finally { ctx.cleanup() }
+	})
+
+	it('§2 scenario re-test: ahead state ends in a successful dry-run with NO revert and NO drift error', () => {
+		// This is the canonical regression test for the original failure.
+		// Setup mirrors §2 exactly: lock 0.3.2, disk 0.3.3 (hand-edited bump),
+		// CHANGELOG already has the 0.3.3 entry. The full publish would need
+		// a real registry — but the orchestration must reach the publish
+		// step cleanly, not block on a misclassified drift error.
+		const ctx = scaffold({
+			full: 'happyskillsai/happyskills-help', short: 'happyskills-help',
+			lock_version: '0.3.2', disk_version: '0.3.3',
+			changelog: '# Changelog\n\n## [0.3.3] - 2026-05-23\n\n### Added\n- directive vs invitation register routing\n'
+		})
+		try {
+			const { code, stdout } = run(['release', 'happyskills-help', '--workspace', 'happyskillsai', '--dry-run', '--json'], { cwd: ctx.root })
+			assert.strictEqual(code, 0, '§2 scenario must NOT block — ahead is normal authoring')
+			const env = parse_json(stdout, '§2 scenario re-test')
+			assert.strictEqual(env.data.dry_run, true)
+			assert.strictEqual(env.data.target_version, '0.3.3', 'must publish the disk version')
+			assert.strictEqual(env.data.ahead_recognized, true)
+			// Snapshot was created and (because dry-run) restored — disk must be unchanged.
+			assert.strictEqual(ctx.read_manifest().version, '0.3.3')
+		} finally { ctx.cleanup() }
+	})
+})

package/src/lock/verify.js

@@ -1,48 +1,183 @@
 const path = require('path')
 const { error: { catch_errors } } = require('puffy-core')
-const { read_json, file_exists } = require('../utils/fs')
+const { read_json, read_file, file_exists } = require('../utils/fs')
+const { gt, lt, valid } = require('../utils/semver')
 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.
+// ──────────────────────────────────────────────────────────────────────────────
+// Lock/disk classification — § 10.5
 //
+// The lock represents the registry view; skill.json represents authoring intent.
+// disk > lock during authoring is normal (`ahead`), NOT drift. We narrow the
+// drift signal to genuine inconsistency only: regression (disk < lock), missing
+// files, or unparseable skill.json.
+//
+// Functions:
+//   - verify_lock_disk_consistency: returns { ok } + (when ok:false) drift detail
+//   - detect_ahead_state:           returns { ahead, lock_version, disk_version, ... }
+//   - classify_lock_disk:           combines both into a single state value
+//   - describe_drift:               plain-English description for human output
+// ──────────────────────────────────────────────────────────────────────────────
+
 // Result shapes:
-//   { ok: true }
+//   { ok: true }                                                          — clean OR ahead (no drift)
 //   { ok: false, reason: 'missing_dir',         expected, actual: null }
 //   { ok: false, reason: 'missing_skill_json',  expected, actual: null }
-//   { ok: false, reason: 'version_mismatch',    expected, actual }
+//   { ok: false, reason: 'regression',          expected, actual }       — disk < lock
+//
+// Note: `regression` REPLACES the previous `version_mismatch` reason for the
+// disk-less-than-lock direction. The disk-greater-than-lock direction is no
+// longer reported as drift — it's the ahead state (see detect_ahead_state).
 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 [, dir_present] = await file_exists(install_dir)
+	if (!dir_present) 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 [, manifest_present] = await file_exists(manifest_path)
+	if (!manifest_present) 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 }
+	if (actual === expected) return { ok: true }
+
+	// Direction-aware classification. If either side is not valid semver we
+	// fall back to a regression label — the safe choice that surfaces the
+	// inconsistency rather than waving it through.
+	if (actual && valid(actual) && valid(expected)) {
+		if (gt(actual, expected)) {
+			// Disk > lock: this is `ahead`, not drift. Report ok.
+			return { ok: true }
+		}
+		if (lt(actual, expected)) {
+			return { ok: false, reason: 'regression', expected, actual }
+		}
+	}
+
+	// actual === null (no version field) OR invalid semver on either side.
+	// Treat missing/invalid version as a corrupted skill.json — closer to
+	// missing_skill_json than to regression.
+	if (!actual) return { ok: false, reason: 'missing_skill_json', expected, actual: null }
+	return { ok: false, reason: 'regression', expected, actual }
+})
+
+// Parse the first ## [<version>] heading from CHANGELOG.md.
+const parse_changelog_top_version = (content) => {
+	if (!content) return null
+	const match = content.match(/^##\s+\[\s*([^\]]+?)\s*\]/m)
+	if (!match) return null
+	const candidate = match[1].trim()
+	return valid(candidate) ? candidate : null
+}
+
+// detect_ahead_state — returns { ahead: bool, lock_version, disk_version,
+// has_changelog_entry, changelog_version }. Pure local read; no registry call.
+//
+// Pre-requisite: the caller already knows verify_lock_disk_consistency.ok === true
+// (i.e. no genuine drift). detect_ahead_state then asks: is disk > lock?
+const detect_ahead_state = (lock_entry, install_dir) => catch_errors('Failed to detect ahead state', async () => {
+	const lock_version = lock_entry?.version || null
+	if (!lock_version) return { ahead: false, lock_version: null, disk_version: null }
+
+	const manifest_path = path.join(install_dir, SKILL_JSON)
+	const [, manifest_present] = await file_exists(manifest_path)
+	if (!manifest_present) return { ahead: false, lock_version, disk_version: null }
+
+	const [, manifest] = await read_json(manifest_path)
+	const disk_version = manifest?.version || null
+	if (!disk_version) return { ahead: false, lock_version, disk_version: null }
+
+	if (!valid(disk_version) || !valid(lock_version)) {
+		return { ahead: false, lock_version, disk_version }
+	}
 
-	return { ok: true }
+	if (!gt(disk_version, lock_version)) {
+		return { ahead: false, lock_version, disk_version }
+	}
+
+	// disk > lock → ahead. Read CHANGELOG for the hint fields.
+	const changelog_path = path.join(install_dir, 'CHANGELOG.md')
+	const [, cl_present] = await file_exists(changelog_path)
+	let changelog_version = null
+	if (cl_present) {
+		const [, cl_content] = await read_file(changelog_path)
+		if (cl_content) changelog_version = parse_changelog_top_version(cl_content)
+	}
+	return {
+		ahead: true,
+		lock_version,
+		disk_version,
+		has_changelog_entry: changelog_version === disk_version,
+		changelog_version
+	}
 })
 
 // Plain-language description of a drift result, suitable for the principal-facing
-// table cell (status column). Returns null when ok.
+// table cell (status column). Returns null when ok or ahead.
 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})`
+	if (verify_result.reason === 'regression') return `drift (regression: lock ${verify_result.expected}, disk ${verify_result.actual})`
 	return 'drift'
 }
 
-module.exports = { verify_lock_disk_consistency, describe_drift }
+// Single classifier producing the seven canonical lock/disk states. Callers
+// that also want registry context (outdated / diverged / conflicts) layer
+// those on top — this function answers the local-only question.
+//
+// Returns one of:
+//   { status: 'clean' }
+//   { status: 'modified', current_integrity?, modified_files? }          // when local_modified is true (callers compute it via detect_status)
+//   { status: 'ahead', ahead: { lock_version, disk_version, has_changelog_entry, changelog_version } }
+//   { status: 'drift', drift: { reason, lock_version, disk_version } }
+//
+// `options.local_modified` lets callers supply the result of detect_status
+// without re-running it; if omitted, the function returns the lock/disk view
+// only (clean / ahead / drift).
+const classify_lock_disk = (lock_entry, install_dir, options = {}) => catch_errors('Failed to classify lock/disk state', async () => {
+	const [verify_err, verify] = await verify_lock_disk_consistency(lock_entry, install_dir)
+	if (verify_err) throw verify_err[0] || verify_err
+	if (!verify.ok) {
+		return {
+			status: 'drift',
+			drift: {
+				reason: verify.reason,
+				lock_version: verify.expected,
+				disk_version: verify.actual
+			}
+		}
+	}
+
+	const [, ahead] = await detect_ahead_state(lock_entry, install_dir)
+	if (ahead && ahead.ahead) {
+		return {
+			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
+			}
+		}
+	}
+
+	if (options.local_modified) {
+		return { status: 'modified' }
+	}
+	return { status: 'clean' }
+})
+
+module.exports = {
+	verify_lock_disk_consistency,
+	detect_ahead_state,
+	describe_drift,
+	classify_lock_disk,
+	parse_changelog_top_version
+}

package/src/lock/verify.test.js

@@ -5,7 +5,13 @@ const os = require('os')
 const path = require('path')
 const fs = require('fs')
 
-const { verify_lock_disk_consistency, describe_drift } = require('./verify')
+const {
+	verify_lock_disk_consistency,
+	detect_ahead_state,
+	describe_drift,
+	classify_lock_disk,
+	parse_changelog_top_version
+} = require('./verify')
 
 const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-verify-test-'))
 const cleanup = (dir) => fs.rmSync(dir, { recursive: true, force: true })
@@ -15,6 +21,11 @@ const write_skill_json = (dir, manifest) => {
 	fs.writeFileSync(path.join(dir, 'skill.json'), JSON.stringify(manifest, null, '\t'))
 }
 
+const write_changelog = (dir, content) => {
+	fs.mkdirSync(dir, { recursive: true })
+	fs.writeFileSync(path.join(dir, 'CHANGELOG.md'), content)
+}
+
 describe('verify_lock_disk_consistency', () => {
 	it('returns ok when lock version matches disk version', async () => {
 		const dir = make_tmp()
@@ -27,14 +38,25 @@ describe('verify_lock_disk_consistency', () => {
 		} finally { cleanup(dir) }
 	})
 
-	it('detects version_mismatch when disk skill.json has a different version (the linwong bug)', async () => {
+	it('returns ok when disk is AHEAD of lock (the §2 authoring-ahead state)', 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 install_dir = path.join(dir, 'happyskills-help')
+			write_skill_json(install_dir, { name: 'happyskills-help', version: '0.3.3' })
+			const [err, result] = await verify_lock_disk_consistency({ version: '0.3.2' }, install_dir)
+			assert.strictEqual(err, null)
+			assert.deepEqual(result, { ok: true }, 'disk > lock is ahead, not drift')
+		} finally { cleanup(dir) }
+	})
+
+	it('reports regression when disk is BEHIND lock (the genuine drift case)', async () => {
+		const dir = make_tmp()
+		try {
+			const install_dir = path.join(dir, 'regressed')
+			write_skill_json(install_dir, { name: 'regressed', 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' })
+			assert.deepEqual(result, { ok: false, reason: 'regression', expected: '0.4.0', actual: '0.3.0' })
 		} finally { cleanup(dir) }
 	})
 
@@ -72,14 +94,14 @@ describe('verify_lock_disk_consistency', () => {
 		} finally { cleanup(dir) }
 	})
 
-	it('detects version_mismatch when disk skill.json has no version field', async () => {
+	it('detects missing_skill_json 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 })
+			assert.deepEqual(result, { ok: false, reason: 'missing_skill_json', expected: '1.0.0', actual: null })
 		} finally { cleanup(dir) }
 	})
 
@@ -104,16 +126,166 @@ describe('verify_lock_disk_consistency', () => {
 	})
 })
 
+describe('detect_ahead_state', () => {
+	it('returns ahead:true when disk > lock', async () => {
+		const dir = make_tmp()
+		try {
+			const install_dir = path.join(dir, 'ahead')
+			write_skill_json(install_dir, { name: 'ahead', version: '0.3.3' })
+			const [err, result] = await detect_ahead_state({ version: '0.3.2' }, install_dir)
+			assert.strictEqual(err, null)
+			assert.strictEqual(result.ahead, true)
+			assert.strictEqual(result.lock_version, '0.3.2')
+			assert.strictEqual(result.disk_version, '0.3.3')
+			assert.strictEqual(result.has_changelog_entry, false)
+			assert.strictEqual(result.changelog_version, null)
+		} finally { cleanup(dir) }
+	})
+
+	it('returns ahead:false when versions match', async () => {
+		const dir = make_tmp()
+		try {
+			const install_dir = path.join(dir, 'match')
+			write_skill_json(install_dir, { name: 'match', version: '1.0.0' })
+			const [err, result] = await detect_ahead_state({ version: '1.0.0' }, install_dir)
+			assert.strictEqual(err, null)
+			assert.strictEqual(result.ahead, false)
+		} finally { cleanup(dir) }
+	})
+
+	it('returns ahead:false when disk < lock (regression)', async () => {
+		const dir = make_tmp()
+		try {
+			const install_dir = path.join(dir, 'regress')
+			write_skill_json(install_dir, { name: 'regress', version: '0.2.0' })
+			const [err, result] = await detect_ahead_state({ version: '0.3.0' }, install_dir)
+			assert.strictEqual(err, null)
+			assert.strictEqual(result.ahead, false)
+		} finally { cleanup(dir) }
+	})
+
+	it('reports has_changelog_entry:true when CHANGELOG top heading matches disk version', async () => {
+		const dir = make_tmp()
+		try {
+			const install_dir = path.join(dir, 'with-cl')
+			write_skill_json(install_dir, { name: 'with-cl', version: '0.3.3' })
+			write_changelog(install_dir, '# Changelog\n\n## [0.3.3] - 2026-05-23\n\n### Added\n- new feature\n')
+			const [err, result] = await detect_ahead_state({ version: '0.3.2' }, install_dir)
+			assert.strictEqual(err, null)
+			assert.strictEqual(result.ahead, true)
+			assert.strictEqual(result.has_changelog_entry, true)
+			assert.strictEqual(result.changelog_version, '0.3.3')
+		} finally { cleanup(dir) }
+	})
+
+	it('reports has_changelog_entry:false when CHANGELOG names a different version', async () => {
+		const dir = make_tmp()
+		try {
+			const install_dir = path.join(dir, 'cl-mismatch')
+			write_skill_json(install_dir, { name: 'cl-mismatch', version: '0.3.3' })
+			write_changelog(install_dir, '# Changelog\n\n## [0.4.0]\n- different\n')
+			const [err, result] = await detect_ahead_state({ version: '0.3.2' }, install_dir)
+			assert.strictEqual(err, null)
+			assert.strictEqual(result.ahead, true)
+			assert.strictEqual(result.has_changelog_entry, false)
+			assert.strictEqual(result.changelog_version, '0.4.0')
+		} finally { cleanup(dir) }
+	})
+})
+
+describe('parse_changelog_top_version', () => {
+	it('returns the version from the first ## [...] heading', () => {
+		assert.strictEqual(parse_changelog_top_version('# Changelog\n\n## [1.2.3]\n- note\n'), '1.2.3')
+	})
+
+	it('handles surrounding whitespace inside brackets', () => {
+		assert.strictEqual(parse_changelog_top_version('## [ 1.2.3 ] - 2026-05-23\n'), '1.2.3')
+	})
+
+	it('returns null when no heading is found', () => {
+		assert.strictEqual(parse_changelog_top_version('# Changelog\n\nNo entries yet.\n'), null)
+	})
+
+	it('returns null when the value is not valid semver', () => {
+		assert.strictEqual(parse_changelog_top_version('## [Unreleased]\n'), null)
+	})
+
+	it('returns null for null/empty content', () => {
+		assert.strictEqual(parse_changelog_top_version(null), null)
+		assert.strictEqual(parse_changelog_top_version(''), null)
+	})
+})
+
+describe('classify_lock_disk', () => {
+	it('returns status:clean when lock and disk agree', async () => {
+		const dir = make_tmp()
+		try {
+			const install_dir = path.join(dir, 'clean')
+			write_skill_json(install_dir, { name: 'clean', version: '1.0.0' })
+			const [err, result] = await classify_lock_disk({ version: '1.0.0' }, install_dir)
+			assert.strictEqual(err, null)
+			assert.deepEqual(result, { status: 'clean' })
+		} finally { cleanup(dir) }
+	})
+
+	it('returns status:ahead when disk > lock', async () => {
+		const dir = make_tmp()
+		try {
+			const install_dir = path.join(dir, 'ahead')
+			write_skill_json(install_dir, { name: 'ahead', version: '0.3.3' })
+			const [err, result] = await classify_lock_disk({ version: '0.3.2' }, install_dir)
+			assert.strictEqual(err, null)
+			assert.strictEqual(result.status, 'ahead')
+			assert.strictEqual(result.ahead.lock_version, '0.3.2')
+			assert.strictEqual(result.ahead.disk_version, '0.3.3')
+		} finally { cleanup(dir) }
+	})
+
+	it('returns status:drift with reason:regression when disk < lock', async () => {
+		const dir = make_tmp()
+		try {
+			const install_dir = path.join(dir, 'regression')
+			write_skill_json(install_dir, { name: 'regression', version: '0.2.0' })
+			const [err, result] = await classify_lock_disk({ version: '0.3.0' }, install_dir)
+			assert.strictEqual(err, null)
+			assert.strictEqual(result.status, 'drift')
+			assert.deepEqual(result.drift, { reason: 'regression', lock_version: '0.3.0', disk_version: '0.2.0' })
+		} finally { cleanup(dir) }
+	})
+
+	it('returns status:drift with reason:missing_dir', async () => {
+		const dir = make_tmp()
+		try {
+			const install_dir = path.join(dir, 'ghost')
+			const [err, result] = await classify_lock_disk({ version: '1.0.0' }, install_dir)
+			assert.strictEqual(err, null)
+			assert.strictEqual(result.status, 'drift')
+			assert.strictEqual(result.drift.reason, 'missing_dir')
+		} finally { cleanup(dir) }
+	})
+
+	it('returns status:modified when caller supplies local_modified=true and lock/disk agree', async () => {
+		const dir = make_tmp()
+		try {
+			const install_dir = path.join(dir, 'mod')
+			write_skill_json(install_dir, { name: 'mod', version: '1.0.0' })
+			const [err, result] = await classify_lock_disk({ version: '1.0.0' }, install_dir, { local_modified: true })
+			assert.strictEqual(err, null)
+			assert.deepEqual(result, { status: 'modified' })
+		} 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', () => {
+	it('describes regression 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)'
+			describe_drift({ ok: false, reason: 'regression', expected: '0.4.0', actual: '0.3.0' }),
+			'drift (regression: lock 0.4.0, disk 0.3.0)'
 		)
 	})