happyskills 0.39.0 → 0.40.0

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.40.0] - 2026-05-03
+
+### Added
+- Propagate the fork relationship to the server on the first `publish` after `happyskills fork`. The CLI now reads `manifest.forked_from.repo` (an `owner/name` string written by the fork command), splits it into `{ workspace, name }`, and includes it in the push payload across all three transport modes: direct push, archive upload, and per-file presigned upload. The API resolves the parent and persists `repos.forked_from`, which feeds the duplicate-detection heuristic (forks-of-active-parents are ineligible to be elected source-of-truth, and the publish-time `duplicates` warning is suppressed when the only match is the fork's parent). Subsequent publishes of an existing repo are unaffected — the field is honored only on the create-repo path. Requires API ≥ 2.4.0.
+
+### Fixed
+- Fix `publish` crashing with a `ReferenceError`/TDZ on `visibility` when validation runs before the spinner update — the `const visibility = args.flags.public ? 'public' : 'private'` declaration was below its first use. Move the declaration ahead of all reads.
+- Fix `validate_manifest` rejecting kit names like `_kit-foo` ("Invalid name … Must start with a letter or number"). Kits are required by `init --kit` and `validate_skill_json` to start with `_kit-`, so the leading-character rule is now carved out for `manifest.type === 'kit'` via a separate `KIT_NAME_PATTERN`. Bumping a kit no longer fails its own pre-publish manifest validation.
+
+## [0.39.1] - 2026-05-01
+
+### Fixed
+- Fix `status` command falsely reporting `local_modified: true` and `status: diverged` for skills whose on-disk content is byte-for-byte identical to the registry baseline. The previous single-stage aggregate-integrity check could disagree with `diff` whenever the lock's `base_integrity` drifted from what `hash_directory` produces today (e.g. server-side normalization of the file set, or differences between the JSON-clone and archive install paths). `detect_status` now falls through to a per-file content comparison against the registry manifest at `base_commit` when the aggregate hash disagrees: zero real diffs → reports clean and silently auto-heals the lock entry's `integrity` / `base_integrity`; one or more real diffs → reports modified and includes the list of differing paths in the new `modified_files` field of the JSON output. Fixes the false-positive that blocked `update` (and required `--force`) and `pull` for skills with stale lock entries. The fast path is unchanged when the aggregate hash matches.
+
 ## [0.39.0] - 2026-05-01
 
 ### Removed

package/package.json

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

package/src/api/push.js

@@ -13,7 +13,7 @@ const estimate_payload_size = (files) => {
 	return size
 }
 
-const archive_push = (owner, repo, { version, message, files, visibility, base_commit, force, parent_shas, source_dir }, on_progress) =>
+const archive_push = (owner, repo, { version, message, files, visibility, base_commit, force, parent_shas, forked_from, source_dir }, on_progress) =>
 	catch_errors('Archive push failed', async () => {
 		const file_meta = files.map(f => ({ path: f.path, sha: f.sha, size: f.size }))
 
@@ -28,6 +28,7 @@ const archive_push = (owner, repo, { version, message, files, visibility, base_c
 				archive: true, archive_sha: archive.sha, archive_size: archive.size
 			}
 			if (parent_shas) init_body.parent_shas = parent_shas
+			if (forked_from) init_body.forked_from = forked_from
 			const [init_err, init_data] = await initiate_upload(owner, repo, init_body)
 			if (init_err) throw e('Upload initiation failed', init_err)
 
@@ -44,6 +45,7 @@ const archive_push = (owner, repo, { version, message, files, visibility, base_c
 				version, message, files: file_meta, base_commit, force
 			}
 			if (parent_shas) complete_body.parent_shas = parent_shas
+			if (forked_from) complete_body.forked_from = forked_from
 			const [complete_err, complete_data] = await complete_upload(owner, repo, complete_body)
 			if (complete_err) throw e('Upload completion failed', complete_err)
 
@@ -62,7 +64,7 @@ const archive_push = (owner, repo, { version, message, files, visibility, base_c
 		}
 	})
 
-const smart_push = (owner, repo, { version, message, files, visibility, base_commit, force, parent_shas, source_dir }, on_progress) =>
+const smart_push = (owner, repo, { version, message, files, visibility, base_commit, force, parent_shas, forked_from, source_dir }, on_progress) =>
 	catch_errors('Smart push failed', async () => {
 		const payload_size = estimate_payload_size(files)
 
@@ -70,6 +72,7 @@ const smart_push = (owner, repo, { version, message, files, visibility, base_com
 			// Small payload — use direct push
 			const body = { version, message, files, visibility, base_commit, force }
 			if (parent_shas) body.parent_shas = parent_shas
+			if (forked_from) body.forked_from = forked_from
 			const [err, data] = await repos_api.push(owner, repo, body)
 			if (err) throw e('Direct push failed', err)
 			return data
@@ -77,7 +80,7 @@ const smart_push = (owner, repo, { version, message, files, visibility, base_com
 
 		// Large payload — prefer archive upload if source_dir is available
 		if (source_dir) {
-			return await archive_push(owner, repo, { version, message, files, visibility, base_commit, force, parent_shas, source_dir }, on_progress)
+			return await archive_push(owner, repo, { version, message, files, visibility, base_commit, force, parent_shas, forked_from, source_dir }, on_progress)
 		}
 
 		// Fallback: per-file presigned upload
@@ -86,6 +89,7 @@ const smart_push = (owner, repo, { version, message, files, visibility, base_com
 		// Step 1: Initiate
 		const init_body = { version, message, files: file_meta, visibility, base_commit, force }
 		if (parent_shas) init_body.parent_shas = parent_shas
+		if (forked_from) init_body.forked_from = forked_from
 		const [init_err, init_data] = await initiate_upload(owner, repo, init_body)
 		if (init_err) throw e('Upload initiation failed', init_err)
 
@@ -111,6 +115,7 @@ const smart_push = (owner, repo, { version, message, files, visibility, base_com
 		// Step 3: Complete
 		const complete_body = { upload_id, version, message, files: file_meta, base_commit, force }
 		if (parent_shas) complete_body.parent_shas = parent_shas
+		if (forked_from) complete_body.forked_from = forked_from
 		const [complete_err, complete_data] = await complete_upload(owner, repo, complete_body)
 		if (complete_err) throw e('Upload completion failed', complete_err)
 

package/src/commands/publish.js

@@ -135,6 +135,8 @@ const run = (args) => catch_errors('Publish failed', async () => {
 
 	const spinner = create_spinner('Preparing to publish...')
 
+	const visibility = args.flags.public ? 'public' : 'private'
+
 	let owner = args.flags.workspace
 	if (!owner) {
 		const [, resolved_owner] = await resolve_skill_owner(skill_name)
@@ -221,7 +223,6 @@ const run = (args) => catch_errors('Publish failed', async () => {
 			spinner.update(`Uploading files (${completed}/${total})...`)
 		}
 	}
-	const visibility = args.flags.public ? 'public' : 'private'
 	const push_options = {
 		version: manifest.version,
 		message: `Release ${manifest.version}`,
@@ -234,6 +235,15 @@ const run = (args) => catch_errors('Publish failed', async () => {
 	if (merge_parents && !force) {
 		push_options.parent_shas = merge_parents
 	}
+
+	// Propagate fork relationship to the server on the first publish.
+	// Only the create-repo path uses this; existing repos already have forked_from set.
+	if (manifest.forked_from && typeof manifest.forked_from.repo === 'string' && manifest.forked_from.repo.includes('/')) {
+		const [parent_workspace, parent_name] = manifest.forked_from.repo.split('/')
+		if (parent_workspace && parent_name) {
+			push_options.forked_from = { workspace: parent_workspace, name: parent_name }
+		}
+	}
 	const [push_err, push_data] = await smart_push(workspace.slug, manifest.name, push_options, on_progress)
 	if (push_err) {
 		const last = push_err[push_err.length - 1]

package/src/commands/publish.test.js

@@ -0,0 +1,21 @@
+const { describe, it } = require('node:test')
+const assert = require('node:assert')
+const fs = require('node:fs')
+const path = require('node:path')
+
+describe('publish.js — Bug 1 regression: visibility temporal-dead-zone', () => {
+	const src = fs.readFileSync(path.join(__dirname, 'publish.js'), 'utf8')
+
+	it('declares `visibility` before passing it to validate_dependencies', () => {
+		const decl_idx = src.search(/const\s+visibility\s*=\s*args\.flags\.public/)
+		const use_idx = src.search(/validate_dependencies\([\s\S]*?visibility/)
+		assert.notStrictEqual(decl_idx, -1, '`const visibility = args.flags.public ? ...` declaration not found')
+		assert.notStrictEqual(use_idx, -1, '`validate_dependencies(... visibility ...)` call not found')
+		assert.ok(
+			decl_idx < use_idx,
+			`visibility must be declared (idx ${decl_idx}) before it is read inside validate_dependencies (idx ${use_idx}). ` +
+			'The current ordering causes `ReferenceError: Cannot access \'visibility\' before initialization` ' +
+			'whenever skill.json declares one or more dependencies.'
+		)
+	})
+})

package/src/commands/pull.js

@@ -152,7 +152,7 @@ const run = (args) => catch_errors('Pull failed', async () => {
 	const spinner = create_spinner(`Pulling ${skill_name}...`)
 
 	// 2. Detect local modifications
-	const [det_err, det] = await detect_status(lock_entry, skill_dir)
+	const [det_err, det] = await detect_status(lock_entry, skill_dir, { skill_name, project_root, is_global })
 	if (det_err) { spinner.fail('Failed to detect local status'); throw det_err[0] }
 
 	// 3. Compare with remote

package/src/commands/status.js

@@ -74,7 +74,7 @@ const run = (args) => catch_errors('Status failed', async () => {
 		if (!data) return { name, data, det: null }
 		const short_name = name.split('/')[1] || name
 		const dir = skill_install_dir(base_dir, short_name)
-		return detect_status(data, dir).then(([, det]) => ({ name, data, det }))
+		return detect_status(data, dir, { skill_name: name, project_root, is_global }).then(([, det]) => ({ name, data, det }))
 	}))
 
 	const results = detections.map(({ name, data, det }) => {
@@ -85,6 +85,7 @@ const run = (args) => catch_errors('Status failed', async () => {
 			base_version: data.version || null,
 			base_commit: data.base_commit || null,
 			local_modified: det?.local_modified || false,
+			modified_files: det?.modified_files || null,
 			// remote_updated is populated below after API call
 			remote_updated: false,
 			remote_version: null,

package/src/commands/update.js

@@ -242,7 +242,7 @@ const run = (args) => catch_errors('Update failed', async () => {
 		const lock_entry = skills[r.skill]
 		const short_name = r.skill.split('/')[1] || r.skill
 		const dir = skill_install_dir(base_dir, short_name)
-		return detect_status(lock_entry, dir).then(([, det]) => ({ r, det }))
+		return detect_status(lock_entry, dir, { skill_name: r.skill, project_root, is_global }).then(([, det]) => ({ r, det }))
 	}))
 
 	const skipped = []

package/src/manifest/validator.js

@@ -2,6 +2,9 @@ const { valid } = require('../utils/semver')
 
 const REQUIRED_FIELDS = ['name', 'version']
 const NAME_PATTERN = /^[a-z0-9][a-z0-9_-]*$/
+// Kits are required to start with `_kit-` (enforced by `init --kit` and
+// validate_skill_json). Carve out the leading-character rule for them.
+const KIT_NAME_PATTERN = /^_kit-[a-z0-9][a-z0-9-]*$/
 
 const validate_manifest = (manifest) => {
 	const errors = []
@@ -12,7 +15,8 @@ const validate_manifest = (manifest) => {
 		}
 	}
 
-	if (manifest.name && !NAME_PATTERN.test(manifest.name)) {
+	const name_pattern = manifest.type === 'kit' ? KIT_NAME_PATTERN : NAME_PATTERN
+	if (manifest.name && !name_pattern.test(manifest.name)) {
 		errors.push(`Invalid name "${manifest.name}". Use lowercase letters, numbers, hyphens, and underscores. Must start with a letter or number.`)
 	}
 

package/src/manifest/validator.test.js

@@ -98,4 +98,26 @@ describe('validate_manifest', () => {
 		const result = validate_manifest({ name: 'my-skill', version: '1.0.0' })
 		assert.strictEqual(result.valid, true)
 	})
+
+	// Bug 2 regression — kit names start with `_kit-` (enforced by `init --kit` and
+	// `validate_skill_json` for type==='kit'). The shared `validate_manifest` used
+	// by `bump` must accept this convention or the standard release workflow breaks.
+	describe('kit name convention', () => {
+		it('accepts a kit name beginning with _kit- when type is "kit"', () => {
+			const result = validate_manifest({ name: '_kit-mykit', version: '1.0.0', type: 'kit' })
+			assert.strictEqual(result.valid, true, `expected valid, got errors: ${result.errors.join(', ')}`)
+		})
+
+		it('still rejects a non-kit manifest whose name starts with _', () => {
+			const result = validate_manifest({ name: '_oops', version: '1.0.0' })
+			assert.strictEqual(result.valid, false)
+			assert.ok(result.errors.some(e => e.includes('Invalid name')))
+		})
+
+		it('still rejects a non-kit manifest whose name starts with _ even if type=skill', () => {
+			const result = validate_manifest({ name: '_oops', version: '1.0.0', type: 'skill' })
+			assert.strictEqual(result.valid, false)
+			assert.ok(result.errors.some(e => e.includes('Invalid name')))
+		})
+	})
 })

package/src/merge/detector.js

@@ -1,31 +1,91 @@
 const { error: { catch_errors } } = require('puffy-core')
 const { hash_directory } = require('../lock/integrity')
+const { find_modified_files } = require('./file_diff')
+const { read_lock, get_all_locked_skills } = require('../lock/reader')
+const { write_lock, update_lock_skills } = require('../lock/writer')
+const { lock_root } = require('../config/paths')
+
+// Serialize lock heals across concurrent detect_status calls so parallel
+// read-modify-write sequences don't clobber each other's updates.
+let heal_chain = Promise.resolve()
+
+const queue_heal = (skill_name, current_integrity, project_root, is_global) => {
+	const next = heal_chain.then(async () => {
+		const root = lock_root(is_global, project_root)
+		const [, lock_data] = await read_lock(root)
+		if (!lock_data) return
+		const skills = get_all_locked_skills(lock_data)
+		const entry = skills[skill_name]
+		if (!entry) return
+		if (entry.base_integrity === current_integrity && entry.integrity === current_integrity) return
+		const updated = { ...entry, base_integrity: current_integrity, integrity: current_integrity }
+		const merged = update_lock_skills(lock_data, { [skill_name]: updated })
+		await write_lock(root, merged)
+		if (process.env.HAPPYSKILLS_DEBUG) {
+			process.stderr.write(`integrity drift auto-healed for ${skill_name}\n`)
+		}
+	}).catch(() => {})
+	heal_chain = next
+	return next
+}
 
 /**
  * Detects whether a skill has been locally modified since install/pull.
  *
- * Compares the current directory hash against the base_integrity recorded
- * in the lock file. If they differ, the user has local modifications.
+ * Two-stage check:
+ *   1. Fast path — compare hash_directory(disk) against lock.base_integrity.
+ *      If they match, the skill is unmodified.
+ *   2. Fallback — when the aggregate hash disagrees, fetch the registry
+ *      manifest at base_commit and compare per-file (git blob SHAs). The
+ *      aggregate hash is only an optimization; the per-file comparison is
+ *      the source of truth.
+ *
+ *      - Zero files differ → the lock's integrity has drifted (e.g. server
+ *        normalized which files are returned). Auto-heal the lock entry's
+ *        integrity / base_integrity to the current value and report clean.
+ *      - One or more files differ → real local modifications. Return them
+ *        in `modified_files` for better diagnostics.
  *
- * @param {object} lock_entry - Lock file entry for the skill
- * @param {string} skill_dir  - Absolute path to the skill directory
- * @returns {[errors, { local_modified, current_integrity, base_integrity, base_commit }]}
+ * The fallback requires `options.skill_name` and a base_commit on the lock;
+ * without them, the function falls back to the legacy pessimistic answer
+ * (local_modified: true on aggregate mismatch).
+ *
+ * @param {object} lock_entry
+ * @param {string} skill_dir
+ * @param {object} [options]
+ * @param {string} [options.skill_name]   - "owner/repo" (enables fallback)
+ * @param {string} [options.project_root] - Project root for lock heal
+ * @param {boolean} [options.is_global]   - Whether to heal the global lock
  */
-const detect_status = (lock_entry, skill_dir) => catch_errors('Failed to detect status', async () => {
+const detect_status = (lock_entry, skill_dir, options = {}) => catch_errors('Failed to detect status', async () => {
 	const base_commit = lock_entry?.base_commit || null
 	const base_integrity = lock_entry?.base_integrity || null
 
-	if (!base_integrity) return { local_modified: false, current_integrity: null, base_integrity: null, base_commit }
+	if (!base_integrity) return { local_modified: false, current_integrity: null, base_integrity: null, base_commit, modified_files: null }
 
 	const [hash_err, current_integrity] = await hash_directory(skill_dir)
-	if (hash_err) return { local_modified: false, current_integrity: null, base_integrity, base_commit }
+	if (hash_err) return { local_modified: false, current_integrity: null, base_integrity, base_commit, modified_files: null }
+
+	if (current_integrity === base_integrity) {
+		return { local_modified: false, current_integrity, base_integrity, base_commit, modified_files: [] }
+	}
 
-	return {
-		local_modified: current_integrity !== base_integrity,
-		current_integrity,
-		base_integrity,
-		base_commit
+	const { skill_name = null, project_root = null, is_global = false } = options
+	if (!skill_name || !base_commit) {
+		return { local_modified: true, current_integrity, base_integrity, base_commit, modified_files: null }
 	}
+
+	const [, modified_files] = await find_modified_files(skill_name, base_commit, skill_dir)
+	if (modified_files === null) {
+		return { local_modified: true, current_integrity, base_integrity, base_commit, modified_files: null }
+	}
+
+	if (modified_files.length === 0) {
+		if (project_root) await queue_heal(skill_name, current_integrity, project_root, is_global)
+		return { local_modified: false, current_integrity, base_integrity: current_integrity, base_commit, modified_files: [], healed: true }
+	}
+
+	return { local_modified: true, current_integrity, base_integrity, base_commit, modified_files }
 })
 
 module.exports = { detect_status }

package/src/merge/detector.test.js

@@ -1,22 +1,40 @@
-const { describe, it, afterEach } = require('node:test')
+const { describe, it, afterEach, before, after } = require('node:test')
 const assert = require('node:assert/strict')
 const fs = require('fs')
 const path = require('path')
 const os = require('os')
-const { detect_status } = require('./detector')
 const { hash_directory, clear_integrity_cache } = require('../lock/integrity')
+const { hash_blob } = require('../utils/git_hash')
 
-const make_tmp = () => {
-	const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'detector-test-'))
-	return dir
+// Stub repos_api before file_diff/detector load it. find_modified_files
+// uses repos_api.clone, so we control its return value via the stub state.
+const repos_api_path = require.resolve('../api/repos')
+const stub_state = { files: [], err: null }
+require.cache[repos_api_path] = {
+	id: repos_api_path,
+	filename: repos_api_path,
+	loaded: true,
+	exports: {
+		clone: async () => stub_state.err
+			? [[stub_state.err], null]
+			: [null, { files: stub_state.files }]
+	}
 }
 
+const { detect_status } = require('./detector')
+
+const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'detector-test-'))
 const rm = (dir) => { try { fs.rmSync(dir, { recursive: true }) } catch (_) {} }
 
 describe('detect_status', () => {
 	let tmp_dir
 
-	afterEach(() => { if (tmp_dir) rm(tmp_dir) })
+	afterEach(() => {
+		if (tmp_dir) { rm(tmp_dir); tmp_dir = null }
+		stub_state.files = []
+		stub_state.err = null
+		clear_integrity_cache()
+	})
 
 	it('returns local_modified: false when integrity matches', async () => {
 		tmp_dir = make_tmp()
@@ -33,13 +51,12 @@ describe('detect_status', () => {
 		assert.equal(result.base_commit, 'abc123')
 	})
 
-	it('returns local_modified: true when integrity differs', async () => {
+	it('returns local_modified: true when integrity differs and no fallback context is given', async () => {
 		tmp_dir = make_tmp()
 		fs.writeFileSync(path.join(tmp_dir, 'SKILL.md'), 'hello')
 
 		const [, integrity] = await hash_directory(tmp_dir)
 
-		// Modify the file and clear hash cache (cache is per-command-invocation optimization)
 		fs.writeFileSync(path.join(tmp_dir, 'SKILL.md'), 'modified')
 		clear_integrity_cache()
 
@@ -48,6 +65,7 @@ describe('detect_status', () => {
 		assert.equal(err, null)
 		assert.equal(result.local_modified, true)
 		assert.notEqual(result.current_integrity, integrity)
+		assert.equal(result.modified_files, null)
 	})
 
 	it('returns local_modified: false when base_integrity is missing', async () => {
@@ -75,4 +93,100 @@ describe('detect_status', () => {
 		assert.equal(err, null)
 		assert.equal(result.local_modified, false)
 	})
+
+	it('auto-heals the lock when aggregate integrity drifts but per-file content matches the registry', async () => {
+		tmp_dir = make_tmp()
+		const project_root = make_tmp()
+
+		const skill_content = 'hello'
+		fs.writeFileSync(path.join(tmp_dir, 'SKILL.md'), skill_content)
+
+		// Stub registry to return the same content the disk has (same git blob sha).
+		stub_state.files = [{ path: 'SKILL.md', sha: hash_blob(Buffer.from(skill_content)) }]
+
+		// Lock has a stale base_integrity that does NOT match the current hash_directory.
+		const stale_integrity = 'sha256-stale0000000000000000000000000000000000000000000000000000000000'
+		const lock_path = path.join(project_root, 'skills-lock.json')
+		fs.writeFileSync(lock_path, JSON.stringify({
+			lockVersion: 2,
+			generatedAt: new Date().toISOString(),
+			skills: {
+				'acme/test-skill': {
+					version: '1.0.0',
+					base_commit: 'abc123',
+					base_integrity: stale_integrity,
+					integrity: stale_integrity
+				}
+			}
+		}))
+
+		const lock_entry = { base_integrity: stale_integrity, base_commit: 'abc123' }
+		const [err, result] = await detect_status(lock_entry, tmp_dir, {
+			skill_name: 'acme/test-skill',
+			project_root,
+			is_global: false
+		})
+
+		assert.equal(err, null)
+		assert.equal(result.local_modified, false)
+		assert.equal(result.healed, true)
+		assert.deepEqual(result.modified_files, [])
+
+		// Wait for the heal write to complete (queued via promise chain).
+		await new Promise(r => setTimeout(r, 50))
+		const lock_after = JSON.parse(fs.readFileSync(lock_path, 'utf-8'))
+		assert.equal(lock_after.skills['acme/test-skill'].base_integrity, result.current_integrity)
+		assert.equal(lock_after.skills['acme/test-skill'].integrity, result.current_integrity)
+
+		rm(project_root)
+	})
+
+	it('reports real local modifications with a list of differing files when fallback runs', async () => {
+		tmp_dir = make_tmp()
+		const project_root = make_tmp()
+
+		fs.writeFileSync(path.join(tmp_dir, 'SKILL.md'), 'edited locally')
+		fs.writeFileSync(path.join(tmp_dir, 'skill.json'), '{}')
+
+		// Registry says SKILL.md should have different content; skill.json matches.
+		stub_state.files = [
+			{ path: 'SKILL.md', sha: hash_blob(Buffer.from('original')) },
+			{ path: 'skill.json', sha: hash_blob(Buffer.from('{}')) }
+		]
+
+		fs.writeFileSync(path.join(project_root, 'skills-lock.json'), JSON.stringify({
+			lockVersion: 2,
+			generatedAt: new Date().toISOString(),
+			skills: {}
+		}))
+
+		const lock_entry = { base_integrity: 'sha256-stale', base_commit: 'abc123' }
+		const [err, result] = await detect_status(lock_entry, tmp_dir, {
+			skill_name: 'acme/test-skill',
+			project_root,
+			is_global: false
+		})
+
+		assert.equal(err, null)
+		assert.equal(result.local_modified, true)
+		assert.deepEqual(result.modified_files, ['SKILL.md'])
+
+		rm(project_root)
+	})
+
+	it('falls back to pessimistic local_modified: true when registry fetch fails', async () => {
+		tmp_dir = make_tmp()
+		fs.writeFileSync(path.join(tmp_dir, 'SKILL.md'), 'hello')
+
+		stub_state.err = new Error('network down')
+
+		const lock_entry = { base_integrity: 'sha256-stale', base_commit: 'abc123' }
+		const [err, result] = await detect_status(lock_entry, tmp_dir, {
+			skill_name: 'acme/test-skill'
+		})
+
+		assert.equal(err, null)
+		assert.equal(result.local_modified, true)
+		assert.equal(result.modified_files, null)
+	})
 })

package/src/merge/file_diff.js

@@ -0,0 +1,68 @@
+const fs = require('fs')
+const path = require('path')
+const { error: { catch_errors } } = require('puffy-core')
+const repos_api = require('../api/repos')
+const { hash_blob } = require('../utils/git_hash')
+
+const build_local_file_shas = (skill_dir) => catch_errors('Failed to build local file shas', async () => {
+	const entries = []
+	const walk = async (dir, prefix) => {
+		let items
+		try {
+			items = await fs.promises.readdir(dir, { withFileTypes: true })
+		} catch {
+			return
+		}
+		for (const item of items) {
+			if (item.name.startsWith('.')) continue
+			const rel = prefix ? `${prefix}/${item.name}` : item.name
+			const full = path.join(dir, item.name)
+			if (item.isDirectory()) {
+				await walk(full, rel)
+			} else if (item.isFile()) {
+				const content = await fs.promises.readFile(full)
+				entries.push({ path: rel, sha: hash_blob(content) })
+			}
+		}
+	}
+	await walk(skill_dir, '')
+	return entries
+})
+
+/**
+ * Compares disk content against the registry baseline at base_commit and
+ * returns the list of paths whose content actually differs. An empty array
+ * means the disk is byte-identical to the registry (per Git blob hashing).
+ *
+ * Returns null when the comparison cannot be performed (network failure,
+ * missing inputs) so callers can fall back to a pessimistic answer.
+ *
+ * @param {string} skill_name - "owner/repo"
+ * @param {string} base_commit
+ * @param {string} skill_dir - Absolute path to the on-disk skill
+ * @returns {[errors, string[]|null]}
+ */
+const find_modified_files = (skill_name, base_commit, skill_dir) => catch_errors('Failed to compare disk to registry', async () => {
+	if (!skill_name || !skill_name.includes('/') || !base_commit) return null
+
+	const [owner, repo] = skill_name.split('/')
+	const [clone_err, clone_data] = await repos_api.clone(owner, repo, null, { commit: base_commit })
+	if (clone_err) return null
+
+	const base_files = clone_data.files || []
+	const base_map = new Map(base_files.map(f => [f.path, f.sha]))
+
+	const [local_err, local_entries] = await build_local_file_shas(skill_dir)
+	if (local_err) return null
+	const local_map = new Map(local_entries.map(e => [e.path, e.sha]))
+
+	const all_paths = new Set([...base_map.keys(), ...local_map.keys()])
+	const modified = []
+	for (const p of all_paths) {
+		if (base_map.get(p) !== local_map.get(p)) modified.push(p)
+	}
+	modified.sort()
+	return modified
+})
+
+module.exports = { find_modified_files, build_local_file_shas }