happyskills 0.48.0 → 0.49.0

package/CHANGELOG.md

@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.49.0] - 2026-05-23
+
+This release combines two streams of work: **spec 260523-02 (Skill Update Determinism)** which introduces four new CLI primitives plus an `ahead` status to make skill update flows deterministic and safe-to-attempt, AND a **bundle-size enforcement** pass that adds a total-bundle cap to pre-publish validation.
+
+### Added
+
+#### Determinism primitives (spec 260523-02)
+
+- **New `snapshot` command** — capture and restore skill state. Subcommands: `create`, `list`, `restore`, `delete`, `prune`. Snapshots live under `.happyskills/snapshots/<workspace>/<skill>/<snapshot_id>/` and contain a full directory copy plus the lock entry. Default retention 10 per skill; auto-prune on create; configurable via `--keep <n>`. Atomic restore via filesystem rename. Surfaced as the safety net for every non-trivial mutation in the new primitives below.
+- **New `reconcile` command** — deterministic drift repair. Diagnoses the drift subtype and either fixes it on the spot (with `--apply <action>`) or emits a structured `next_step` envelope for operator adjudication. **No-ops on `ahead`** (disk version > lock — that's normal authoring, not drift). Replaces the prose drift-repair procedure that previously routed through `install --fresh`.
+- **New `release` command** — atomic release pipeline. Wraps snapshot + validate + bump (when needed) + changelog verification + publish + lock update + snapshot cleanup as a single deterministic CLI invocation. Recognizes the `ahead` state directly: when `skill.json` is already ahead of lock, the disk version IS the version to publish — no revert, no re-bump. On any failure restores the snapshot and returns a structured `next_step` envelope (`fix_validation_errors`, `specify_bump_type`, `provide_changelog`, `pull_rebase_first`, `specify_workspace`, `reconcile_first`, `resolve_bump_disagreement`).
+- **New `pull --rebase` flag** — snapshot-backed rebase-style pull. Captures local edits as patches, fast-forwards to the registry head, reapplies the patches. On rejection emits a structured envelope with per-file expected/actual context so an operator (LLM) can produce a corrected patch without re-reading the entire file. The standard 3-way merge mode remains the default.
+
+#### Status taxonomy (spec 260523-02 § 10.5)
+
+- **New `ahead` top-level status** in `list`, `status`, and `check` JSON envelopes. Indicates the normal authoring-ahead state (disk version > lock version) — the author has bumped locally and not yet published. Carries an `ahead: { lock_version, disk_version, has_changelog_entry, changelog_version }` object. Replaces the previous false-positive `drift.version_mismatch` classification for this case.
+- **Narrowed `drift` reasons.** The previous `version_mismatch` reason is removed; `drift.reason` now ranges over `regression` (disk semver-LESS than lock), `missing_skill_json`, and `missing_dir`. Drift is now strictly genuine inconsistency in the local install record.
+
+#### `install --fresh` hardening (spec 260523-02 § 8.5)
+
+- **Pre-flight version-existence check.** Before any disk mutation, `install <skill>@<version> --fresh` calls the registry to confirm `<version>` exists. If not (or registry unreachable), hard-fails with `USAGE_ERROR` (exit 2) and a `VERSION_NOT_FOUND` message. **Closes the silent-fallback footgun** documented in spec 260523-02 § 2.3 — previously the CLI quietly installed the latest published version when the requested version was missing, with no error envelope.
+- **Snapshot-first.** When the skill directory exists, `--fresh` now captures a snapshot before wiping and exposes `data.snapshot_id` in the success response so the operator can restore manually if needed.
+- **New `--force-discard-local` flag.** When the skill directory has local edits (integrity hash differs from `base_integrity`), `--fresh` refuses with `LOCAL_EDITS_PRESENT` (exit 2) unless `--force-discard-local` is passed. Makes the "throw away my edits" intent explicit.
+
+#### Bundle-size enforcement
+
+- **New `cli/src/config/limits.js`** — single source of truth for the size limits enforced before publish. Exports `MAX_FILE_SIZE` (1 MB per file) and `MAX_TOTAL_SIZE` (1 MB total bundle). The header comment pins this file as the mirror of `api/app/config/limits.js`; drift between the two will cause the API to reject a publish that the CLI just told the user was fine, so they must be bumped together.
+- **New `max_total_size` validation rule** in `cli/src/validation/file_size_rules.js`. The rule sums the bytes of every non-hidden, non-`node_modules` file under the skill directory and fails pre-publish validation when the total exceeds `MAX_TOTAL_SIZE`. Previously only the per-file `max_file_size` rule existed — a skill made of many sub-1 MB files whose total exceeded the bundle cap would pass `happyskills validate` locally and only fail server-side at `POST /push/initiate` with a `PAYLOAD_TOO_LARGE`. The new rule surfaces the same verdict locally with a clearer message (`"Skill bundle exceeds 1MB limit (X.XX MB)"`) before any presigned-URL or upload work happens.
+
+### Changed
+
+- **`bump` no longer touches the lock file** (spec 260523-02 § 8.6). Previously `bump` updated both `skill.json` and the lock entry atomically. Under the new lock-as-registry-view principle, a local bump is not a registry interaction — the lock catches up at publish time, atomically with registry acceptance. After bump, the skill enters the `ahead` state until the next publish. Hand-editing `skill.json`'s version field is now functionally equivalent to `bump` for the lock contract (both produce `ahead`); `bump` retains its ergonomic advantages (validation, semver arithmetic, remote-exists warning) but is no longer privileged for correctness.
+- **`publish` now writes the lock file on first publish.** Previously the lock-write block was gated on an existing lock file; in fresh projects (no lock yet), first publish succeeded against the registry but left no local lock entry, causing downstream `list`/`status`/`check` to treat the just-published skill as external. Now `publish` initializes a new lock structure if none exists and persists the new entry atomically.
+- **`list`/`status`/`check` human output** updated to surface the `ahead` state distinctly from `drift`. Stale guidance pointing users at `install --fresh` for drift repair replaced with pointers to `reconcile`.
+- **`pull.js`** dispatches to a new `merge/rebase.js` module when `--rebase` is set; the existing 3-way merge mode is unchanged.
+- **`cli/src/validation/file_size_rules.js`** no longer hardcodes its own `1 * 1024 * 1024` literal — it imports `MAX_FILE_SIZE` and `MAX_TOTAL_SIZE` from `cli/src/config/limits.js`. Same numeric behavior for the per-file rule; the user-facing message now interpolates the limit from the constant rather than reading "1MB" verbatim, so a future bump only requires editing the config file.
+- **CLI registers four new commands** in `constants.js` (`snapshot`, `reconcile`, `release`, plus the `pull --rebase` flag on the existing `pull` command). `index.js` help text updated to surface them.
+
+### Fixed
+
+- **Silent first-publish lock-creation bug.** `publish.js`'s lock-write was wrapped in `if (!lock_err && lock_data)` so a fresh project (no lock file) silently never created one even after a successful registry publish. The newly-published skill then appeared as `external` in `list` output. Unrelated to spec 260523-02 in origin but surfaced during its E2E verification.
+
+### Notes for skill authors
+
+- The CLI status taxonomy change is observable: code that depended on `drift.reason === "version_mismatch"` should now branch on `status === "ahead"` for the disk > lock case, or on `drift.reason === "regression"` for disk < lock. All first-party HappySkills skills (`happyskills`, `happyskills-publish`, `happyskills-sync`) have been updated and require this CLI version or newer (`requires.happyskills >= 0.49.0`).
+- The `bump` behavior change is observable but strictly safer. No documented contract was broken: bump's lock-update was internal bookkeeping, not a published interface. Third-party code that depended on `bump` keeping the lock in sync should switch to `release` (which performs the atomic update at publish time as designed).
+- `install --fresh @<missing-version>` previously succeeded with a silent fallback; it now fails fast. Strictly safer — any legitimate caller is rare and would benefit from the explicit error.
+
 ## [0.48.0] - 2026-05-22
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.48.0",
+	"version": "0.49.0",
 	"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

@@ -6,9 +6,6 @@ const { inc, valid } = require('../utils/semver')
 const { resolve_skill_dir } = require('../utils/resolve_skill')
 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, code } = require('../ui/output')
 const { exit_with_error, UsageError } = require('../utils/errors')
@@ -52,13 +49,15 @@ const run = (args) => catch_errors('Bump failed', async () => {
 
 	const old_version = manifest.version
 
-	// Read lock file early to resolve full skill name for remote check + lock update
+	// Read lock file only to resolve the full skill name for the remote
+	// existence warning. The lock is NOT updated here — bump only touches
+	// skill.json. The lock catches up at publish time, atomically with
+	// registry acceptance. (Spec 260523-02 § 8.6.)
 	const project_root = find_project_root()
 	const [lock_err, lock_data] = await read_lock(project_root)
 	let lock_key = null
-	let all_skills = null
 	if (!lock_err && lock_data) {
-		all_skills = get_all_locked_skills(lock_data)
+		const all_skills = get_all_locked_skills(lock_data)
 		const suffix = `/${skill_name}`
 		lock_key = Object.keys(all_skills).find(k => k.endsWith(suffix)) || null
 	}
@@ -90,29 +89,10 @@ const run = (args) => catch_errors('Bump failed', async () => {
 	const [write_err] = await write_manifest(dir, manifest)
 	if (write_err) throw e('Failed to update skill.json', write_err)
 
-	if (lock_key && all_skills?.[lock_key]) {
-		const [hash_err, integrity] = await hash_directory(dir)
-		const updated_entry = {
-			...all_skills[lock_key],
-			version: manifest.version,
-			ref: `refs/tags/v${manifest.version}`
-		}
-		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.`
-			)
-		}
-	}
+	// § 8.6: bump no longer updates the lock. The lock represents what was
+	// last successfully installed or published from the registry, and a
+	// local bump is not a registry interaction. The skill enters the `ahead`
+	// state (disk version > lock version) until the next publish.
 
 	if (args.flags.json) {
 		const bump_type = BUMP_TYPES.includes(input) ? input : 'explicit'

package/src/commands/check.js

@@ -1,6 +1,6 @@
 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 { verify_lock_disk_consistency, detect_ahead_state } = 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')
@@ -63,21 +63,39 @@ const run = (args) => catch_errors('Check failed', async () => {
 	// 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.
+	// Also detect the ahead state — disk > lock is normal authoring, not drift,
+	// and should be reported as such per §10.5.
 	const base_dir = skills_dir(false, project_root)
 	const drift_by_skill = {}
+	const ahead_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
+		if (drift && !drift.ok) {
+			drift_by_skill[name] = drift
+			return
+		}
+		const [, ahead] = await detect_ahead_state(data, dir)
+		if (ahead && ahead.ahead) ahead_by_skill[name] = ahead
 	}))
 
+	const build_ahead_obj = (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
+	})
+
 	const results = []
 	if (batch_err) {
 		for (const [name, data] of to_check) {
 			const drift = drift_by_skill[name]
+			const ahead = ahead_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 if (ahead) {
+				results.push({ skill: name, installed: data.version, latest: '-', status: 'ahead', via: get_via(data), ahead: build_ahead_obj(ahead) })
 			} else {
 				results.push({ skill: name, installed: data.version, latest: 'error', status: 'error', via: get_via(data) })
 			}
@@ -88,8 +106,11 @@ const run = (args) => catch_errors('Check failed', async () => {
 			const via = get_via(data)
 			const has_conflicts = (data.conflict_files || []).length > 0
 			const drift = drift_by_skill[name]
+			const ahead = ahead_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 (ahead) {
+				results.push({ skill: name, installed: data.version, latest: info?.latest_version || '-', status: 'ahead', via, ahead: build_ahead_obj(ahead) })
 			} else if (has_conflicts) {
 				results.push({ skill: name, installed: data.version, latest: info?.latest_version || '-', status: 'conflicts', via })
 			} else if (info?.access_denied) {
@@ -112,7 +133,8 @@ const run = (args) => catch_errors('Check failed', async () => {
 		const up_to_date_count = results.filter(r => r.status === 'up-to-date').length
 		const conflicts_count = results.filter(r => r.status === 'conflicts').length
 		const drift_count = results.filter(r => r.status === 'drift').length
-		print_json({ data: { results, outdated_count, up_to_date_count, conflicts_count, drift_count } })
+		const ahead_count = results.filter(r => r.status === 'ahead').length
+		print_json({ data: { results, outdated_count, up_to_date_count, conflicts_count, drift_count, ahead_count } })
 		return
 	}
 
@@ -121,6 +143,7 @@ const run = (args) => catch_errors('Check failed', async () => {
 		'outdated': yellow,
 		'conflicts': red,
 		'drift': red,
+		'ahead': (s) => s,
 		'no-access': yellow,
 		'error': red,
 		'unknown': (s) => s
@@ -153,7 +176,16 @@ const run = (args) => catch_errors('Check failed', async () => {
 			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.`)
+		print_hint(`Repair with ${code('happyskills reconcile <skill>')}.`)
+	}
+	const ahead_results = results.filter(r => r.status === 'ahead')
+	if (ahead_results.length > 0) {
+		console.log()
+		print_info(`${ahead_results.length} skill(s) ahead of lock — bumped locally, not yet published.`)
+		for (const a of ahead_results) {
+			console.error(`  - ${a.skill} (lock ${a.ahead?.lock_version}, disk ${a.ahead?.disk_version})`)
+		}
+		print_hint(`Publish with ${code('happyskills publish <skill>')}.`)
 	}
 	if (conflicts.length > 0) {
 		console.log()

package/src/commands/install.js

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

package/src/commands/list.js

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

package/src/commands/publish.js

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

package/src/commands/pull.js

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