happyskills 0.47.1 → 0.49.0

package/CHANGELOG.md

@@ -7,6 +7,69 @@ 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
+- Add `--search-output <file>` flag to `happyskills postlex`. When set, postlex reads the full `search --with-rerank --json` response envelope from that file and extracts `data.results` internally — the calling agent's stdin payload shrinks to just `{"ranking": [...]}`. **Recommended path** for agentic callers: the agent never has to construct the `data` array by hand, which eliminates two observed failure modes in production (missing `data` field consuming the one retry budget, and `skill` vs `name` field mismatch dropping every ranking entry). Backward-compatible: the legacy `{"ranking", "data"}` stdin shape and the separate `--data <file>` flag both still work and take precedence only when `--search-output` is absent.
+
+### Fixed
+- Fix `to_smart_json` in `search.js` stripping the bare `name` field from `data.results` rows. The function emitted `skill` (the composite "workspace/name" slug) but consumed the underlying `name` field into the template literal, so downstream consumers of `data.results` — most notably `happyskills postlex` — received rows without a usable `name`. postlex's `validate_ranking` then dropped every ranking entry with `data row missing name`. The function now emits both `name` (raw, for downstream pipeline consumers) AND `skill` (composite, for human-readable display), keeping backward compatibility with anything reading `skill`.
+- Add `star_count` to `to_smart_json` output (in addition to the existing `stars` field) so `postlex`'s human-readable table renderer — which expected `row.star_count` — can find the value on rows that originated from the search response. Same root cause as the `name` issue: the search-output and postlex-input shapes had drifted apart silently.
+- Add `resolve_row_name` + `normalize_data_rows` helpers in `postlex.js` that handle the legacy case where `data.results` rows have `skill` but no `name`. `resolve_row_name` falls back to the last `/`-separated segment of `skill`; `normalize_data_rows` runs the resolution across the array. Idempotent. This is defense-in-depth — anyone passing rows from an older CLI version or a hand-crafted payload no longer trips the validator.
+
+### Changed
+- `parse_input` in `postlex.js` accepts a new optional third argument carrying the raw `--search-output` content. When provided, it's parsed and `data.results` is extracted via `extract_data_array_from_search_output`, which tolerates the canonical envelope shape (`{ data: { results: [...] } }`), the legacy `{ data: [...] }` shape, a bare array, and a defensive double-wrapped `{ data: { data: [...] } }`. When both inline `data` (from the stdin payload) and `--search-output` are provided, the search-output wins.
+- `postlex`'s help text rewritten to lead with the recommended `--search-output` recipe and demote the legacy stdin `{ranking, data}` shape to a "still supported" alternative.
+- When `data` cannot be located from any source (no inline `data`, no `--data` file, no `--search-output`), the error message now points the caller at `--search-output` explicitly so they know which input is missing.
+
 ## [0.47.1] - 2026-05-22
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.47.1",
+	"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/postlex.js

@@ -32,22 +32,61 @@ Required:
   --ranking <file|->          Path to the ranking JSON, or \`-\` for stdin
 
 Optional:
-  --data <file>               Separate data file (when --ranking does not embed it)
+  --search-output <file>      Path to the full \`search --with-rerank --json\` response
+                              envelope. postlex extracts \`data.results\` from it
+                              internally, so the ranking payload only needs the
+                              ranking array. **Recommended path** for agentic
+                              callers — eliminates the join the agent would
+                              otherwise have to assemble by hand.
+  --data <file>               Legacy: separate data file (when --ranking does not
+                              embed it AND --search-output isn't used)
   --clarification-turns-used <N>
                               Clarification budget already spent (0-2, default 0)
   --original-query <q>        Original user query (opaque context from prior step)
   --json                      Output as JSON (default: human-readable table)
 
-Input shape (stdin or --ranking file):
-  { "ranking": [{ "rank": 1, "candidate_id": 5, "rationale": "..." }, ...],
-    "data":    [{ "name": "...", "workspace_slug": "...", ... }, ...] }
+Recommended shape (v0.48.0+) — agent emits ONLY the ranking, postlex does the join:
+  echo '{"ranking":[{"rank":1,"candidate_id":5,"rationale":"..."}, ...]}' | \\
+    happyskills postlex --query "deploy aws" \\
+                        --search-output /tmp/search-out.json \\
+                        --ranking -
 
-Examples:
+Legacy shape (still supported):
   echo '{"ranking":[...],"data":[...]}' | happyskills postlex --query "deploy aws" --ranking -
   happyskills postlex --query "deploy aws" --ranking r.json --data d.json --json`
 
 // ─── Pure logic — exported for unit testing ────────────────────────────────
 
+// Resolve a candidate's bare name, tolerating multiple field conventions.
+// The API row shape has `name`. The CLI's `to_smart_json` output (as of
+// happyskills@0.48.0) emits both `name` and the composite `skill`
+// ("workspace/name"). Older callers may pass through rows that only have
+// `skill`, so we fall back to extracting the bare name from the slug's last
+// `/`-separated segment. Returns null when no name can be derived.
+const resolve_row_name = (row) => {
+	if (!row || typeof row !== 'object') return null
+	if (typeof row.name === 'string' && row.name) return row.name
+	if (typeof row.skill === 'string' && row.skill) {
+		const parts = row.skill.split('/')
+		const tail = parts[parts.length - 1]
+		if (tail) return tail
+	}
+	return null
+}
+
+// Mutate `data` rows in-place to ensure they have a `name` field.
+// Idempotent. Used before validate_ranking / apply_postlex / build_final_ordering
+// so downstream code can keep its simple `row.name` access pattern.
+const normalize_data_rows = (data) => {
+	if (!Array.isArray(data)) return
+	for (const row of data) {
+		if (row && typeof row === 'object' && !row.name) {
+			const resolved = resolve_row_name(row)
+			if (resolved) row.name = resolved
+		}
+	}
+}
+
 // Validate the ranking shape. Returns { valid_items, dropped } — invalid
 // entries are dropped with a reason rather than crashing.
 const validate_ranking = (ranking, data) => {
@@ -204,9 +243,33 @@ const read_stdin_sync = () => {
 	}
 }
 
-const parse_input = (raw_ranking_input, raw_data_input) => {
-	// Accept either combined `{ranking, data}` from stdin/one file, or
-	// separate `{ranking: ...}`/`{data: ...}` (or bare arrays) from two files.
+// Extract the data array (the rerank candidate set) from a full
+// `happyskills search --with-rerank --json` response envelope. The
+// envelope's shape is `{ data: { query, mode, results: [...], ... },
+// error, next_step }` — we want `envelope.data.results`. Also tolerates a
+// bare array, a `{data: [...]}` shape (legacy callers), and the
+// `{data: {data: [...]}}` shape that appears if someone double-wraps.
+// Returns the array, or null when no array can be located.
+const extract_data_array_from_search_output = (parsed) => {
+	if (Array.isArray(parsed)) return parsed
+	if (!parsed || typeof parsed !== 'object') return null
+	const inner = parsed.data
+	if (Array.isArray(inner)) return inner
+	if (inner && typeof inner === 'object') {
+		if (Array.isArray(inner.results)) return inner.results
+		if (Array.isArray(inner.data)) return inner.data
+	}
+	if (Array.isArray(parsed.results)) return parsed.results
+	return null
+}
+
+const parse_input = (raw_ranking_input, raw_data_input, raw_search_output_input) => {
+	// Accept either:
+	//   - combined `{ranking, data}` from stdin/one file (legacy v0.47.x shape), OR
+	//   - separate ranking + data files (`--ranking <file>` + `--data <file>`), OR
+	//   - just `{ranking: ...}` or a bare ranking array PLUS a `--search-output` file
+	//     containing the full search envelope from which we extract `data.results`
+	//     (v0.48.0+ recommended shape — agent never has to construct `data`).
 	const parse_one = (raw, label) => {
 		if (raw == null || raw === '') return { value: null, parse_error: `${label} input is empty` }
 		try {
@@ -240,8 +303,25 @@ const parse_input = (raw_ranking_input, raw_data_input) => {
 		else return { ranking, data: null, parse_error: 'data file does not contain a data array' }
 	}
 
+	if (raw_search_output_input != null) {
+		const so_parse = parse_one(raw_search_output_input, 'search-output')
+		if (so_parse.parse_error) return { ranking, data, parse_error: so_parse.parse_error }
+		const extracted = extract_data_array_from_search_output(so_parse.value)
+		if (!Array.isArray(extracted)) {
+			return { ranking, data: null, parse_error: 'search-output does not contain a data.results array' }
+		}
+		// search-output is the recommended source — it overrides any inline data.
+		data = extracted
+	}
+
 	if (!Array.isArray(ranking)) return { ranking: null, data, parse_error: 'ranking field is missing or not an array' }
-	if (!Array.isArray(data))    return { ranking, data: null, parse_error: 'data field is missing or not an array' }
+	if (!Array.isArray(data))    return { ranking, data: null, parse_error: 'data field is missing or not an array — provide --search-output <file> with the search response, or include "data" in the stdin payload' }
+
+	// Normalize row names (handles the `skill`-without-`name` case from older
+	// CLI versions or hand-crafted payloads). Idempotent on rows that already
+	// have a `name` field.
+	normalize_data_rows(data)
+
 	return { ranking, data, parse_error: null }
 }
 
@@ -287,6 +367,7 @@ const run = (args) => catch_errors('Postlex failed', async () => {
 	const query                       = args.flags.query
 	const ranking_path                = args.flags.ranking
 	const data_path                   = args.flags.data
+	const search_output_path          = args.flags['search-output']
 	const clarification_turns_used    = parseInt(args.flags['clarification-turns-used'] || '0', 10) || 0
 
 	if (!query || typeof query !== 'string')
@@ -309,9 +390,16 @@ const run = (args) => catch_errors('Postlex failed', async () => {
 			return r.content
 		})()
 		: null
+	const raw_search_output = search_output_path
+		? (() => {
+			const r = read_file(search_output_path)
+			if (r.err) throw new UsageError(`Cannot read --search-output file: ${r.err}`)
+			return r.content
+		})()
+		: null
 
 	// Parse
-	const { ranking, data, parse_error } = parse_input(raw_ranking, raw_data)
+	const { ranking, data, parse_error } = parse_input(raw_ranking, raw_data, raw_search_output)
 	if (parse_error) {
 		process.stderr.write(`postlex: ${parse_error}\n`)
 		const env = build_retry_envelope(query, parse_error, clarification_turns_used, 0)
@@ -399,4 +487,7 @@ module.exports = {
 	determine_next_step,
 	build_retry_envelope,
 	parse_input,
+	resolve_row_name,
+	normalize_data_rows,
+	extract_data_array_from_search_output,
 }