happyskills 0.48.0 → 0.49.0

package/src/integration/bump.test.js

@@ -0,0 +1,170 @@
+'use strict'
+/**
+ * Integration tests for `happyskills bump` — § 8.6 (bump narrowed to
+ * skill.json only). After bump, skill.json's version is the new value AND
+ * the lock entry's version is UNCHANGED. Subsequent `list --json` reports
+ * the skill as `status: "ahead"`.
+ *
+ * This test prevents regression of the lock-as-registry-view principle:
+ * a local bump is not a registry interaction, so the lock has no business
+ * being mutated by it.
+ */
+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-bump-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 one locked-and-installed skill.
+const scaffold = ({ full, short, lock_version, disk_version }) => {
+	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: bump test skill\n---\nbody\n`
+	)
+	fs.writeFileSync(
+		path.join(skill_dir, 'skill.json'),
+		JSON.stringify({
+			name: short,
+			version: disk_version,
+			type: 'skill',
+			description: 'bump test skill'
+		}, null, '\t')
+	)
+	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_lock: () => JSON.parse(fs.readFileSync(path.join(root, 'skills-lock.json'), 'utf-8')),
+		read_manifest: () => JSON.parse(fs.readFileSync(path.join(skill_dir, 'skill.json'), 'utf-8')),
+		cleanup: () => fs.rmSync(root, { recursive: true, force: true })
+	}
+}
+
+describe('bump — § 8.6 narrowed to skill.json only', () => {
+	it('updates skill.json version but leaves the lock entry UNCHANGED', () => {
+		const ctx = scaffold({ full: 'acme/my-skill', short: 'my-skill', lock_version: '1.0.0', disk_version: '1.0.0' })
+		try {
+			const { code, stdout } = run(['bump', 'patch', 'my-skill', '--json'], { cwd: ctx.root })
+			assert.strictEqual(code, 0, `bump should exit 0, got ${code}`)
+			const out = parse_json(stdout, 'bump --json')
+			assert.strictEqual(out.data.old_version, '1.0.0')
+			assert.strictEqual(out.data.new_version, '1.0.1')
+
+			// Manifest was updated.
+			assert.strictEqual(ctx.read_manifest().version, '1.0.1', 'skill.json must be at the new version')
+
+			// Lock entry was NOT updated.
+			const lock = ctx.read_lock()
+			assert.strictEqual(
+				lock.skills['acme/my-skill'].version,
+				'1.0.0',
+				'lock entry version must be UNCHANGED — lock catches up at publish time, not bump time'
+			)
+			assert.strictEqual(
+				lock.skills['acme/my-skill'].ref,
+				'refs/tags/v1.0.0',
+				'lock entry ref must be UNCHANGED'
+			)
+			assert.strictEqual(
+				lock.skills['acme/my-skill'].integrity,
+				'sha256-baseline',
+				'lock entry integrity must be UNCHANGED'
+			)
+		} finally { ctx.cleanup() }
+	})
+
+	it('subsequent list --json reports the bumped skill as status:ahead', () => {
+		const ctx = scaffold({ full: 'acme/my-skill', short: 'my-skill', lock_version: '0.3.2', disk_version: '0.3.2' })
+		try {
+			const { code: bump_code } = run(['bump', 'patch', 'my-skill', '--json'], { cwd: ctx.root })
+			assert.strictEqual(bump_code, 0)
+
+			const { code, stdout } = run(['list', '--json'], { cwd: ctx.root })
+			assert.strictEqual(code, 0)
+			const out = parse_json(stdout, 'list --json')
+			const entry = out.data.skills['acme/my-skill']
+			assert.ok(entry, 'skill must appear in list output')
+			assert.strictEqual(entry.status, 'ahead', 'must be ahead, not drift, not installed')
+			assert.strictEqual(entry.ahead.lock_version, '0.3.2')
+			assert.strictEqual(entry.ahead.disk_version, '0.3.3')
+			assert.strictEqual(entry.drift, undefined, 'ahead must not emit a drift object')
+		} finally { ctx.cleanup() }
+	})
+
+	it('explicit version bump leaves lock untouched', () => {
+		const ctx = scaffold({ full: 'acme/exact', short: 'exact', lock_version: '0.1.0', disk_version: '0.1.0' })
+		try {
+			const { code } = run(['bump', '2.5.7', 'exact', '--json'], { cwd: ctx.root })
+			assert.strictEqual(code, 0)
+			assert.strictEqual(ctx.read_manifest().version, '2.5.7')
+			assert.strictEqual(ctx.read_lock().skills['acme/exact'].version, '0.1.0', 'lock untouched')
+		} finally { ctx.cleanup() }
+	})
+
+	it('bump still works when there is no lock entry for the skill at all', () => {
+		// e.g. a freshly-init'd skill that has never been published. There's
+		// no lock key to update, and that's fine — bump only writes to
+		// skill.json.
+		const root = make_tmp()
+		try {
+			const skill_dir = path.join(root, '.agents', 'skills', 'fresh')
+			fs.mkdirSync(skill_dir, { recursive: true })
+			fs.writeFileSync(
+				path.join(skill_dir, 'SKILL.md'),
+				'---\nname: fresh\ndescription: never-published skill\n---\nbody\n'
+			)
+			fs.writeFileSync(
+				path.join(skill_dir, 'skill.json'),
+				JSON.stringify({ name: 'fresh', version: '0.1.0', type: 'skill', description: 'never-published skill' }, null, '\t')
+			)
+			// No skills-lock.json at all.
+			const { code } = run(['bump', 'minor', 'fresh', '--json'], { cwd: root })
+			assert.strictEqual(code, 0)
+			const manifest = JSON.parse(fs.readFileSync(path.join(skill_dir, 'skill.json'), 'utf-8'))
+			assert.strictEqual(manifest.version, '0.2.0')
+		} finally { fs.rmSync(root, { recursive: true, force: true }) }
+	})
+})

package/src/integration/drift.test.js

@@ -108,7 +108,7 @@ const scaffold_drifted = (skills) => {
 // ─── status ───────────────────────────────────────────────────────────────────
 
 describe('status — drift detection', () => {
-	it('reports drift when lock version differs from disk skill.json version (the linwong bug)', () => {
+	it('reports drift:regression when disk version is BEHIND lock (the linwong bug, now narrowed)', () => {
 		const { root, cleanup } = scaffold_drifted([
 			{ full: 'happyskillsai/happyskills-design', short: 'happyskills-design', lock_version: '0.4.0', disk_version: '0.3.0' }
 		])
@@ -120,14 +120,35 @@ describe('status — drift detection', () => {
 			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',
+				reason: 'regression',
 				lock_version: '0.4.0',
 				disk_version: '0.3.0'
 			})
 		} finally { cleanup() }
 	})
 
-	it('drift outranks modified — does not mislabel structural drift as local edits', () => {
+	it('reports status:ahead when disk version is AHEAD of lock (the §2 normal authoring case)', () => {
+		// The §2 incident's trigger state: agent hand-edited skill.json from
+		// 0.3.2 -> 0.3.3, lock still at 0.3.2. Under the new semantics this is
+		// the normal `ahead` state, NOT drift. Asserting this prevents the false
+		// positive from coming back.
+		const { root, cleanup } = scaffold_drifted([
+			{ full: 'happyskillsai/happyskills-help', short: 'happyskills-help', lock_version: '0.3.2', disk_version: '0.3.3' }
+		])
+		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-help')
+			assert.ok(result, 'result must be present')
+			assert.strictEqual(result.status, 'ahead', 'disk > lock must be reported as ahead, not drift')
+			assert.strictEqual(result.drift, null, 'ahead must not emit a drift object')
+			assert.strictEqual(result.ahead.lock_version, '0.3.2')
+			assert.strictEqual(result.ahead.disk_version, '0.3.3')
+		} finally { cleanup() }
+	})
+
+	it('drift:regression 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' }
@@ -138,6 +159,7 @@ describe('status — drift detection', () => {
 			const out = parse_json(stdout, 'status --json')
 			const result = out.data.results[0]
 			assert.strictEqual(result.status, 'drift', 'must be drift, not modified')
+			assert.strictEqual(result.drift.reason, 'regression')
 			assert.notStrictEqual(result.status, 'modified', 'modified would mislead — this is structural drift, not user edits')
 		} finally { cleanup() }
 	})
@@ -188,7 +210,7 @@ describe('status — drift detection', () => {
 // ─── check ────────────────────────────────────────────────────────────────────
 
 describe('check — drift detection', () => {
-	it('reports drift even when the registry API is unreachable', () => {
+	it('reports drift:regression 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([
@@ -202,13 +224,30 @@ describe('check — drift detection', () => {
 			assert.ok(result, 'result must be present even with API down')
 			assert.strictEqual(result.status, 'drift')
 			assert.deepEqual(result.drift, {
-				reason: 'version_mismatch',
+				reason: 'regression',
 				lock_version: '0.4.0',
 				disk_version: '0.3.0'
 			})
 		} finally { cleanup() }
 	})
 
+	it('reports status:ahead when disk > lock even with no registry access', () => {
+		const { root, cleanup } = scaffold_drifted([
+			{ full: 'acme/ahead-only', short: 'ahead-only', lock_version: '0.3.2', disk_version: '0.3.3' }
+		])
+		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/ahead-only')
+			assert.ok(result)
+			assert.strictEqual(result.status, 'ahead')
+			assert.strictEqual(result.ahead.lock_version, '0.3.2')
+			assert.strictEqual(result.ahead.disk_version, '0.3.3')
+			assert.strictEqual(out.data.ahead_count, 1)
+		} 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' },
@@ -239,8 +278,8 @@ describe('check — drift detection', () => {
 
 // ─── list ─────────────────────────────────────────────────────────────────────
 
-describe('list — drift surfacing', () => {
-	it('list --json marks drifted skills with status "drift" and a drift object', () => {
+describe('list — drift and ahead surfacing', () => {
+	it('list --json marks drifted skills with status "drift" and a regression 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' }
@@ -251,12 +290,28 @@ describe('list — drift surfacing', () => {
 			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',
+				reason: 'regression',
 				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)
+			assert.strictEqual(out.data.skills['acme/clean'].ahead, undefined)
+		} finally { cleanup() }
+	})
+
+	it('list --json marks ahead skills with status "ahead" and an ahead object (no drift)', () => {
+		const { root, cleanup } = scaffold_drifted([
+			{ full: 'acme/ahead', short: 'ahead', lock_version: '0.3.2', disk_version: '0.3.3' }
+		])
+		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/ahead'].status, 'ahead')
+			assert.strictEqual(out.data.skills['acme/ahead'].drift, undefined)
+			assert.strictEqual(out.data.skills['acme/ahead'].ahead.lock_version, '0.3.2')
+			assert.strictEqual(out.data.skills['acme/ahead'].ahead.disk_version, '0.3.3')
 		} finally { cleanup() }
 	})
 })

package/src/integration/install_fresh.test.js

@@ -0,0 +1,167 @@
+'use strict'
+/**
+ * Integration tests for `happyskills install --fresh` — § 8.5 hardening.
+ *
+ * This closes the § 2 root cause B: previously, `install <skill>@<version> --fresh`
+ * silently fell back to the latest published version when the requested version
+ * didn't exist. The hardened command must:
+ *   (a) hard-fail with VERSION_NOT_FOUND before any disk mutation,
+ *   (b) snapshot before wiping when the directory exists,
+ *   (c) refuse on local edits unless --force-discard-local.
+ *
+ * These tests force the registry to be unreachable, which exercises the
+ * pre-flight failure mode — the version cannot be verified, so --fresh
+ * refuses. That's exactly the safety behavior the spec requires.
+ */
+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-install-fresh-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 scaffold_installed = ({ full, short, version, modified }) => {
+	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: install-fresh test skill\n---\nbody\n`
+	)
+	fs.writeFileSync(
+		path.join(skill_dir, 'skill.json'),
+		JSON.stringify({ name: short, version, type: 'skill', description: 'install-fresh test skill' }, null, '\t')
+	)
+	const { hash_directory } = require('../lock/integrity')
+
+	// Compute the clean baseline integrity *before* applying any modification.
+	// hash_directory caches results — we'd otherwise get the dirty hash.
+	let lock_integrity
+	// eslint-disable-next-line no-async-promise-executor
+	return new Promise(async (res) => {
+		const { clear_integrity_cache } = require('../lock/integrity')
+		clear_integrity_cache()
+		const [, clean_hash] = await hash_directory(skill_dir)
+		lock_integrity = clean_hash
+
+		if (modified) {
+			clear_integrity_cache()
+			fs.writeFileSync(path.join(skill_dir, 'SKILL.md'), '---\nname: ' + short + '\ndescription: install-fresh test skill\n---\nMUTATED BODY\n')
+		}
+
+		fs.writeFileSync(path.join(root, 'skills-lock.json'), JSON.stringify({
+			lockVersion: 2,
+			generatedAt: new Date().toISOString(),
+			skills: {
+				[full]: {
+					version,
+					type: 'skill',
+					ref: `refs/tags/v${version}`,
+					commit: 'lockcommit',
+					integrity: lock_integrity,
+					base_commit: 'lockcommit',
+					base_integrity: lock_integrity,
+					requested_by: ['__root__'],
+					dependencies: {}
+				}
+			}
+		}, null, '\t'))
+
+		res({
+			root,
+			skill_dir,
+			read_lock: () => JSON.parse(fs.readFileSync(path.join(root, 'skills-lock.json'), 'utf-8')),
+			read_manifest: () => JSON.parse(fs.readFileSync(path.join(skill_dir, 'skill.json'), 'utf-8')),
+			read_skill_md: () => fs.readFileSync(path.join(skill_dir, 'SKILL.md'), 'utf-8'),
+			cleanup: () => fs.rmSync(root, { recursive: true, force: true })
+		})
+	})
+}
+
+describe('install --fresh — § 8.5 hardening', () => {
+	it('hard-fails with VERSION_NOT_FOUND when registry is unreachable (no silent fallback)', async () => {
+		const ctx = await scaffold_installed({ full: 'acme/test', short: 'test', version: '1.0.0' })
+		try {
+			const { code, stderr, stdout } = run(
+				['install', 'acme/test@0.3.3', '--fresh', '--json', '-y'],
+				{ cwd: ctx.root }
+			)
+			// Exit code 2 (USER_ERROR) per spec § 8.5.
+			assert.strictEqual(code, 2, 'must exit with USER_ERROR (2), not silently succeed')
+			// Combined output must mention VERSION_NOT_FOUND.
+			const combined = stdout + stderr
+			assert.match(combined, /VERSION_NOT_FOUND/, 'must surface VERSION_NOT_FOUND, not silently fall back to latest')
+			// JSON envelope's error.code must be USAGE_ERROR (not bare ERROR) so
+			// downstream consumers can parse on the code rather than the message.
+			const json_match = stdout.match(/^{[\s\S]*}\s*$/m)
+			if (json_match) {
+				const parsed = JSON.parse(json_match[0])
+				assert.strictEqual(parsed.error?.code, 'USAGE_ERROR', `error.code must be USAGE_ERROR, got ${parsed.error?.code}`)
+			}
+
+			// Critical: disk content must be UNCHANGED — no silent overwrite.
+			assert.strictEqual(ctx.read_manifest().version, '1.0.0', 'skill.json must NOT have been overwritten')
+		} finally { ctx.cleanup() }
+	})
+
+	it('refuses --fresh when local edits are present unless --force-discard-local', async () => {
+		const ctx = await scaffold_installed({ full: 'acme/edited', short: 'edited', version: '1.0.0', modified: true })
+		try {
+			const { code, stdout, stderr } = run(
+				['install', 'acme/edited@1.0.0', '--fresh', '--json', '-y'],
+				{ cwd: ctx.root }
+			)
+			// Should hard-fail at the LOCAL_EDITS_PRESENT step (before any registry call would matter).
+			assert.notStrictEqual(code, 0, 'must not succeed silently')
+			const combined = stdout + stderr
+			// Either LOCAL_EDITS_PRESENT (preferred, when registry is unreachable
+			// and we never get to the version check, we still expect LOCAL_EDITS
+			// to surface — but registry-failure currently runs first, surfacing
+			// VERSION_NOT_FOUND). Either way, NO silent overwrite must occur.
+			assert.ok(
+				/LOCAL_EDITS_PRESENT|VERSION_NOT_FOUND/.test(combined),
+				`must refuse to clobber local edits, got: ${combined}`
+			)
+			// The mutated content must still be on disk.
+			assert.ok(/MUTATED BODY/.test(ctx.read_skill_md()), 'local mutation must be preserved')
+		} finally { ctx.cleanup() }
+	})
+
+	it('does NOT pre-flight when --fresh is omitted (existing behavior preserved)', async () => {
+		// Without --fresh, the hardening doesn't kick in. The install will fail
+		// when it tries to actually reach the registry, but for a DIFFERENT
+		// reason than VERSION_NOT_FOUND — and no snapshot is taken.
+		const ctx = await scaffold_installed({ full: 'acme/no-fresh', short: 'no-fresh', version: '1.0.0' })
+		try {
+			const { code, stdout, stderr } = run(
+				['install', 'acme/no-fresh@0.3.3', '--json', '-y'],
+				{ cwd: ctx.root }
+			)
+			const combined = stdout + stderr
+			// The fail path may produce many error shapes; the key invariant
+			// is that the hardening's specific VERSION_NOT_FOUND error message
+			// does NOT appear (because hardening only triggers on --fresh).
+			assert.ok(
+				!/VERSION_NOT_FOUND: .* refusing to proceed/.test(combined),
+				'VERSION_NOT_FOUND hardening should not fire without --fresh'
+			)
+			// Disk should still be untouched (whether the install succeeded or
+			// failed via a different error).
+			assert.strictEqual(ctx.read_manifest().version, '1.0.0')
+		} finally { ctx.cleanup() }
+	})
+})

package/src/integration/reconcile.test.js

@@ -0,0 +1,188 @@
+'use strict'
+/**
+ * Integration tests for `happyskills reconcile` — § 8.4. The command's
+ * single job: handle GENUINE drift (regression / missing_skill_json /
+ * missing_dir / corrupted) deterministically when possible, emit next_step
+ * envelopes when user adjudication is required, and **no-op on the `ahead`
+ * state** (ahead is not drift; it routes back to publish).
+ *
+ * These tests prevent the spec § 17.7 anti-pattern from recurring — the
+ * earlier draft auto-repaired `ahead` here, which was exactly the category
+ * error that produced the § 2 incident.
+ */
+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-reconcile-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}`) }
+}
+
+const scaffold = ({ full, short, lock_version, disk_version, omit_skill_json, omit_dir }) => {
+	const root = make_tmp()
+	const skill_dir = path.join(root, '.agents', 'skills', short)
+	if (!omit_dir) {
+		fs.mkdirSync(skill_dir, { recursive: true })
+		fs.writeFileSync(
+			path.join(skill_dir, 'SKILL.md'),
+			`---\nname: ${short}\ndescription: reconcile test skill\n---\nbody\n`
+		)
+		if (!omit_skill_json) {
+			fs.writeFileSync(
+				path.join(skill_dir, 'skill.json'),
+				JSON.stringify({ name: short, version: disk_version, type: 'skill', description: 'reconcile test skill' }, null, '\t')
+			)
+		}
+	}
+	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('reconcile — § 8.4', () => {
+	it('reports clean (no work to do) when lock and disk agree', () => {
+		const ctx = scaffold({ full: 'acme/clean', short: 'clean', lock_version: '1.0.0', disk_version: '1.0.0' })
+		try {
+			const { code, stdout } = run(['reconcile', 'acme/clean', '--json'], { cwd: ctx.root })
+			assert.strictEqual(code, 0)
+			const out = parse_json(stdout, 'reconcile clean')
+			assert.strictEqual(out.data.no_drift, true)
+			assert.strictEqual(out.data.status, 'clean')
+			assert.strictEqual(out.next_step, null)
+		} finally { ctx.cleanup() }
+	})
+
+	it('NO-OPS on ahead (disk > lock) — points back to publish, does NOT mutate', () => {
+		// This is the spec § 17.7 anti-pattern test: the earlier design
+		// auto-repaired ahead via revert-and-rebump. That behavior is rejected.
+		const ctx = scaffold({ full: 'acme/ahead', short: 'ahead', lock_version: '0.3.2', disk_version: '0.3.3' })
+		try {
+			const { code, stdout } = run(['reconcile', 'acme/ahead', '--json'], { cwd: ctx.root })
+			assert.strictEqual(code, 0)
+			const out = parse_json(stdout, 'reconcile ahead')
+			assert.strictEqual(out.data.no_drift, true)
+			assert.strictEqual(out.data.status, 'ahead')
+			assert.strictEqual(out.data.ahead.lock_version, '0.3.2')
+			assert.strictEqual(out.data.ahead.disk_version, '0.3.3')
+			assert.strictEqual(out.next_step, null, 'must NOT emit a next_step for ahead — it is not drift')
+			assert.match(out.hint, /publish/i, 'hint should point at publish/release, not at repair')
+
+			// Confirm no file mutation.
+			assert.strictEqual(ctx.read_manifest().version, '0.3.3', 'skill.json must be unchanged')
+			assert.strictEqual(ctx.read_lock().skills['acme/ahead'].version, '0.3.2', 'lock must be unchanged')
+		} finally { ctx.cleanup() }
+	})
+
+	it('emits resolve_regression next_step for disk < lock', () => {
+		const ctx = scaffold({ full: 'acme/regression', short: 'regression', lock_version: '0.4.0', disk_version: '0.3.0' })
+		try {
+			const { code, stdout } = run(['reconcile', 'acme/regression', '--json'], { cwd: ctx.root })
+			assert.strictEqual(code, 0)
+			const out = parse_json(stdout, 'reconcile regression')
+			assert.strictEqual(out.data.drift_state, 'regression')
+			assert.ok(out.next_step)
+			assert.strictEqual(out.next_step.action, 'resolve_regression')
+			assert.ok(out.next_step.context.options.includes('restore_from_lock_version'))
+			assert.ok(out.next_step.context.options.includes('accept_disk_as_explicit_downgrade'))
+		} finally { ctx.cleanup() }
+	})
+
+	it('--apply restore_from_lock_version repairs a regression deterministically', () => {
+		const ctx = scaffold({ full: 'acme/fix-regression', short: 'fix-regression', lock_version: '0.4.0', disk_version: '0.3.0' })
+		try {
+			const { code, stdout } = run(['reconcile', 'acme/fix-regression', '--apply', 'restore_from_lock_version', '--json'], { cwd: ctx.root })
+			assert.strictEqual(code, 0)
+			const out = parse_json(stdout, 'reconcile regression apply')
+			assert.strictEqual(out.data.applied.applied, 'restore_from_lock_version')
+			assert.strictEqual(out.data.applied.new_disk_version, '0.4.0')
+			assert.strictEqual(out.next_step, null)
+
+			// skill.json now matches the lock.
+			assert.strictEqual(ctx.read_manifest().version, '0.4.0')
+			// Lock untouched (it was the source of truth).
+			assert.strictEqual(ctx.read_lock().skills['acme/fix-regression'].version, '0.4.0')
+		} finally { ctx.cleanup() }
+	})
+
+	it('emits resolve_missing_skill_json next_step when skill.json is absent', () => {
+		const ctx = scaffold({
+			full: 'acme/no-manifest', short: 'no-manifest',
+			lock_version: '1.0.0', disk_version: '1.0.0', omit_skill_json: true
+		})
+		try {
+			const { code, stdout } = run(['reconcile', 'acme/no-manifest', '--json'], { cwd: ctx.root })
+			assert.strictEqual(code, 0)
+			const out = parse_json(stdout, 'reconcile missing-manifest')
+			assert.strictEqual(out.data.drift_state, 'missing_skill_json')
+			assert.strictEqual(out.next_step.action, 'resolve_missing_skill_json')
+			assert.ok(out.next_step.context.options.includes('restore_from_git'))
+			assert.ok(out.next_step.context.options.includes('restore_from_registry_at_lock_version'))
+			assert.ok(out.next_step.context.options.includes('abandon'))
+		} finally { ctx.cleanup() }
+	})
+
+	it('emits resolve_missing_dir next_step when the skill directory is gone', () => {
+		const ctx = scaffold({
+			full: 'acme/no-dir', short: 'no-dir',
+			lock_version: '1.0.0', disk_version: '1.0.0', omit_dir: true
+		})
+		try {
+			const { code, stdout } = run(['reconcile', 'acme/no-dir', '--json'], { cwd: ctx.root })
+			assert.strictEqual(code, 0)
+			const out = parse_json(stdout, 'reconcile missing-dir')
+			assert.strictEqual(out.data.drift_state, 'missing_dir')
+			assert.strictEqual(out.next_step.action, 'resolve_missing_dir')
+			assert.ok(out.next_step.context.options.includes('reinstall_at_lock_version'))
+			assert.ok(out.next_step.context.options.includes('abandon'))
+		} finally { ctx.cleanup() }
+	})
+
+	it('resolves bare skill name from the lock file', () => {
+		const ctx = scaffold({ full: 'acme/bare', short: 'bare', lock_version: '1.0.0', disk_version: '1.0.0' })
+		try {
+			const { code, stdout } = run(['reconcile', 'bare', '--json'], { cwd: ctx.root })
+			assert.strictEqual(code, 0)
+			const out = parse_json(stdout, 'reconcile bare')
+			assert.strictEqual(out.data.skill, 'acme/bare')
+			assert.strictEqual(out.data.no_drift, true)
+		} finally { ctx.cleanup() }
+	})
+})