happyskills 0.54.0 → 1.0.1

package/src/commands/postlex.js

@@ -4,7 +4,7 @@
 //
 // Spec 260521-01 v2 § 5.2 — this command is the deterministic safety net
 // for the rerank protocol. Frontier model emits ranking → postlex finalizes
-// → agent renders. The envelope makes the protocol legible to the agent
+// → agent renders. The canonical six-key response envelope makes the protocol legible to the agent
 // without piling conditional logic into SKILL.md.
 
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
@@ -178,61 +178,92 @@ const determine_next_step = (final_ordering, query, clarification_turns_used) =>
 
 	if (all_strong || final_ordering.length === 0) {
 		return {
+			kind:         'continuation',
 			action:       'present_to_user',
 			instructions: 'Render `data.final_ordering` as a table to the user, with skill name, slug, description, and rationale. Include `data.formulated_query` in your preamble.',
-			context:      null,
+			context:      { original_query: query, clarification_turns_used: turns_used },
 		}
 	}
 
 	if (turns_remaining <= 0) {
 		return {
+			kind:         'continuation',
 			action:       'present_to_user',
 			instructions: 'Even after reranking, no top result is a strong match — but the clarification budget (2 turns) is spent. Render `data.final_ordering` honestly: note that no result was a strong match, and present what you have so the user can decide. Do NOT ask another clarifying question.',
-			context:      null,
+			context:      { original_query: query, clarification_turns_used: turns_used },
 		}
 	}
 
 	return {
-		action: 'clarify',
-		instructions: `After reranking, no top result is a strong match. Ask the user one of \`suggested_questions\` using your agent's question mechanism (e.g. AskUserQuestion in Claude Code), then re-run search with the refined query and add --clarification-turns-used ${turns_used + 1}. The last option is always "Just search anyway" — honor it by re-running with the original query unchanged.`,
-		suggested_questions: [
-			{
-				question: 'After reranking I still don\'t have a strong match. Could you narrow the scope a bit?',
-				options: [
-					{ label: 'Focus on a specific stack (Node / Python / Go / etc.)',  refined_query_hint: 'stack-specific' },
-					{ label: 'Focus on a specific platform (AWS / GCP / Vercel / etc.)', refined_query_hint: 'platform-specific' },
-					{ label: 'Broaden the search — show me more options',                refined_query_hint: 'broader' },
-					{ label: 'Just search anyway',                                       refined_query_hint: null },
-				],
-			},
-		],
-		max_turns_remaining: turns_remaining,
+		kind:         'clarification',
+		action:       'clarify_query',
+		instructions: `After reranking, no top result is a strong match. Ask the user one of \`context.suggested_questions\` using your agent's question mechanism (e.g. AskUserQuestion in Claude Code), then re-run search with the refined query and add --clarification-turns-used ${turns_used + 1}. The last option is always "Just search anyway" — honor it by re-running with the original query unchanged.`,
 		context: {
 			original_query:           query,
 			clarification_turns_used: turns_used,
+			max_turns_remaining:      turns_remaining,
+			suggested_questions: [
+				{
+					question: 'After reranking I still don\'t have a strong match. Could you narrow the scope a bit?',
+					options: [
+						{ label: 'Focus on a specific stack (Node / Python / Go / etc.)',  refined_query_hint: 'stack-specific' },
+						{ label: 'Focus on a specific platform (AWS / GCP / Vercel / etc.)', refined_query_hint: 'platform-specific' },
+						{ label: 'Broaden the search — show me more options',                refined_query_hint: 'broader' },
+						{ label: 'Just search anyway',                                       refined_query_hint: null },
+					],
+				},
+			],
 		},
+		principal_authorization_required: true,
 	}
 }
 
+// ─── next_step consumers (pure — exported for unit testing) ─────────────────
+// run() reacts to the next_step that determine_next_step emitted: it fires a
+// `clarify_triggered` telemetry beacon and renders a clarification notice in
+// text mode. Those two decisions are factored out here so they can be
+// unit-tested without spawning the process or hitting the telemetry endpoint.
+
+// True when the emitted next_step is the post-rerank clarification step.
+// The closed action enum value is `clarify_query` (next_step_actions.js) —
+// matching the bare label "clarify" here silently disables the clarification
+// beacon and notice, since determine_next_step never emits "clarify".
+const is_clarify_next_step = (next_step) =>
+	!!next_step && next_step.action === 'clarify_query'
+
+// The first suggested clarifying question to surface in text mode, or null.
+// suggested_questions lives under next_step.context (spec § 4.5), not at the
+// bare next_step root.
+const first_clarify_question = (next_step) => {
+	const list = next_step && next_step.context && next_step.context.suggested_questions
+	const q = Array.isArray(list) && list[0]
+	return q && typeof q.question === 'string' ? q.question : null
+}
+
 // Envelope used when the LLM's ranking is malformed and we need to ask it
-// to re-emit. The CLI exits 0 — the protocol continues via the envelope.
-const build_retry_envelope = (query, reason, clarification_turns_used, retry_count) => ({
-	data:  null,
-	error: {
-		code:      'ranking_schema_mismatch',
-		message:   reason,
-		exit_code: 0,
-	},
-	next_step: {
-		action:       'retry_rank',
-		instructions: 'Your ranking failed validation. Re-emit a JSON object matching the `rerank_response_schema` from the original search response, then re-pipe to `happyskills postlex --query "<q>" --ranking -`. Max one retry — if it fails again, render the search results without rerank (the API\'s relevance_score order is the fallback).',
-		context: {
-			original_query:           query,
-			clarification_turns_used: clarification_turns_used | 0,
-			retry_count:              (retry_count | 0) + 1,
+// to re-emit. Returns the canonical six-key response envelope (spec § 4) so postlex
+// can be unit-tested against the closed schema.
+const build_retry_envelope = (query, reason, clarification_turns_used, retry_count) => {
+	const { build_envelope } = require('../ui/envelope')
+	return build_envelope({
+		data: {},
+		error: {
+			code:    'RANKING_SCHEMA_MISMATCH',
+			message: reason,
 		},
-	},
-})
+		next_step: {
+			kind:         'recovery',
+			action:       'retry_rank',
+			instructions: 'Your ranking failed validation. Re-emit a JSON object matching the `rerank_response_schema` from the original search response, then re-pipe to `happyskills postlex --query "<q>" --ranking -`. Max one retry — if it fails again, render the search results without rerank (the API\'s relevance_score order is the fallback).',
+			context: {
+				original_query:           query,
+				clarification_turns_used: clarification_turns_used | 0,
+				retry_count:              (retry_count | 0) + 1,
+			},
+		},
+		meta_overrides: { command: 'postlex' },
+	})
+}
 
 // ─── I/O helpers ───────────────────────────────────────────────────────────
 
@@ -405,7 +436,10 @@ const run = (args) => catch_errors('Postlex failed', async () => {
 		process.stderr.write(`postlex: ${parse_error}\n`)
 		const env = build_retry_envelope(query, parse_error, clarification_turns_used, 0)
 		print_json(env)
-		return process.exit(EXIT_CODES.SUCCESS)
+		// Spec § 9.2 — process exit code must mirror meta.exit_code. The
+		// retry envelope carries error.code=RANKING_SCHEMA_MISMATCH which
+		// maps to a non-zero exit; honor that rather than forcing 0.
+		return process.exit(env.meta.exit_code)
 	}
 
 	// Validate per-item
@@ -438,7 +472,7 @@ const run = (args) => catch_errors('Postlex failed', async () => {
 		promoted_from_rank,
 		exact_match_count_in_window,
 	})
-	if (next_step.action === 'clarify') {
+	if (is_clarify_next_step(next_step)) {
 		fire_discovery_telemetry({
 			event:        'clarify_triggered',
 			intent_id,
@@ -475,9 +509,9 @@ const run = (args) => catch_errors('Postlex failed', async () => {
 		console.log(format_human_row(row))
 		if (i < final_ordering.length - 1) console.log('')
 	})
-	if (next_step.action === 'clarify') {
+	if (is_clarify_next_step(next_step)) {
 		console.log(`\n  ${yellow('No top result is a strong match. Suggested clarification:')}`)
-		console.log(`  ${dim(next_step.suggested_questions[0].question)}`)
+		console.log(`  ${dim(first_clarify_question(next_step))}`)
 	} else if (next_step.action === 'present_to_user' && !final_ordering.slice(0, 3).every(r => STRONG_TIERS.has(r.match_quality))) {
 		console.log(`\n  ${yellow('No top result is a strong match (clarification budget spent).')}`)
 	}
@@ -491,6 +525,8 @@ module.exports = {
 	apply_postlex,
 	build_final_ordering,
 	determine_next_step,
+	is_clarify_next_step,
+	first_clarify_question,
 	build_retry_envelope,
 	parse_input,
 	resolve_row_name,

package/src/commands/postlex.test.js

@@ -14,6 +14,8 @@ const {
 	apply_postlex,
 	build_final_ordering,
 	determine_next_step,
+	is_clarify_next_step,
+	first_clarify_question,
 	build_retry_envelope,
 	parse_input,
 	resolve_row_name,
@@ -172,25 +174,32 @@ describe('determine_next_step', () => {
 		rationale:      '',
 	}))
 
-	it('emits present_to_user when top 3 are all strong/good', () => {
+	// Per spec 260525-cli-default-json § 7.1 the closed action names are
+	// "clarify_query" (kind=clarification) and "present_to_user"
+	// (kind=continuation). Tests below use those — the older bare "clarify"
+	// label is deprecated.
+
+	it('emits present_to_user (kind=continuation) when top 3 are all strong/good', () => {
 		const ns = determine_next_step(fo(['strong', 'good', 'strong']), 'q', 0)
 		assert.equal(ns.action, 'present_to_user')
+		assert.equal(ns.kind, 'continuation')
 	})
 
-	it('emits clarify when top 3 include a partial AND budget remains', () => {
+	it('emits clarify_query (kind=clarification) when top 3 include a partial AND budget remains', () => {
 		const ns = determine_next_step(fo(['strong', 'partial', 'good']), 'q', 0)
-		assert.equal(ns.action, 'clarify')
-		assert.equal(ns.max_turns_remaining, 2)
+		assert.equal(ns.action, 'clarify_query')
+		assert.equal(ns.kind, 'clarification')
+		// max_turns_remaining + suggested_questions live inside context (spec § 4.5).
+		assert.equal(ns.context.max_turns_remaining, 2)
 		assert.equal(ns.context.clarification_turns_used, 0)
-		// Always includes a "Just search anyway" option.
-		const last = ns.suggested_questions[0].options[ns.suggested_questions[0].options.length - 1]
+		const last = ns.context.suggested_questions[0].options[ns.context.suggested_questions[0].options.length - 1]
 		assert.match(last.label, /search anyway/i)
 	})
 
-	it('emits clarify when top 3 include a weak/null AND budget remains', () => {
+	it('emits clarify_query when top 3 include a weak/null AND budget remains', () => {
 		const ns = determine_next_step(fo(['weak', 'good', null]), 'q', 1)
-		assert.equal(ns.action, 'clarify')
-		assert.equal(ns.max_turns_remaining, 1)
+		assert.equal(ns.action, 'clarify_query')
+		assert.equal(ns.context.max_turns_remaining, 1)
 	})
 
 	it('emits present_to_user with budget-spent note when budget exhausted', () => {
@@ -201,7 +210,7 @@ describe('determine_next_step', () => {
 
 	it('clamps clarification_turns_used to [0, 2]', () => {
 		const ns_neg = determine_next_step(fo(['partial', 'partial', 'partial']), 'q', -1)
-		assert.equal(ns_neg.max_turns_remaining, 2)
+		assert.equal(ns_neg.context.max_turns_remaining, 2)
 		const ns_big = determine_next_step(fo(['partial', 'partial', 'partial']), 'q', 99)
 		assert.equal(ns_big.action, 'present_to_user')
 	})
@@ -217,17 +226,75 @@ describe('determine_next_step', () => {
 	})
 })
 
+// ─── next_step consumer wiring (clarify_query drift regression) ────────────
+// determine_next_step (the producer) emits next_step.action === "clarify_query"
+// with suggested_questions nested under next_step.context (spec § 4.5). run()'s
+// telemetry + text-render consumers must recognize that exact contract. The
+// historical bug: the consumers checked for the bare label "clarify" and read
+// next_step.suggested_questions at the wrong depth, so the clarify_triggered
+// beacon never fired and the clarification notice never rendered — a SILENT
+// failure (no error) at the one moment the harness is meant to engage.
+describe('postlex clarify_query consumer wiring', () => {
+	const weak_ordering = [
+		{ rank: 1, candidate_id: 1, match_quality: 'weak' },
+		{ rank: 2, candidate_id: 2, match_quality: 'partial' },
+		{ rank: 3, candidate_id: 3, match_quality: 'weak' },
+	]
+
+	it('recognizes the producer\'s clarify_query next_step (telemetry + render gate)', () => {
+		const ns = determine_next_step(weak_ordering, 'deploy aws', 0)
+		assert.equal(ns.action, 'clarify_query', 'producer emits the canonical action')
+		assert.equal(
+			is_clarify_next_step(ns), true,
+			'consumer must recognize action "clarify_query" so the clarify_triggered beacon fires and the notice renders',
+		)
+	})
+
+	it('reads the suggested question from next_step.context.suggested_questions', () => {
+		const ns = determine_next_step(weak_ordering, 'deploy aws', 0)
+		const q = first_clarify_question(ns)
+		assert.equal(typeof q, 'string', 'suggested question must be resolved from next_step.context')
+		assert.ok(q.length > 0, 'must surface the first suggested clarifying question for text-mode rendering')
+	})
+
+	it('does not treat the success path (present_to_user) as a clarify step', () => {
+		const ns = determine_next_step(
+			[
+				{ rank: 1, candidate_id: 1, match_quality: 'strong' },
+				{ rank: 2, candidate_id: 2, match_quality: 'good' },
+				{ rank: 3, candidate_id: 3, match_quality: 'strong' },
+			],
+			'q', 0,
+		)
+		assert.equal(ns.action, 'present_to_user')
+		assert.equal(is_clarify_next_step(ns), false)
+		assert.equal(first_clarify_question(ns), null)
+	})
+})
+
 // ─── build_retry_envelope ─────────────────────────────────────────────────
+// Envelope contract: six-key { ok, data, error, next_step, warnings, meta }
+// with data={}, error.code=RANKING_SCHEMA_MISMATCH (closed enum), kind=recovery,
+// action=retry_rank, exit_code mirrored on meta (NOT on error).
+
+const { validate_envelope } = require('../schema/envelope_validator')
 
 describe('build_retry_envelope', () => {
-	it('produces a retry_rank envelope with all required fields', () => {
+	it('produces a retry_rank envelope conforming to the closed schema', () => {
 		const env = build_retry_envelope('the query', 'ranking missing field rationale', 1, 0)
-		assert.equal(env.data, null)
-		assert.equal(env.error.code, 'ranking_schema_mismatch')
-		assert.equal(env.error.exit_code, 0)
+		const { ok, errors } = validate_envelope(env)
+		assert.equal(ok, true, `envelope failed validation: ${JSON.stringify(errors)}`)
+		assert.equal(env.ok, false, 'retry envelope is a failure (ok=false)')
+		assert.deepEqual(env.data, {}, 'data must be the empty object, never null')
+		assert.equal(env.error.code, 'RANKING_SCHEMA_MISMATCH')
+		assert.equal(typeof env.error.message, 'string')
+		assert.equal('exit_code' in env.error, false, 'exit_code lives on meta, not error')
+		assert.equal(env.next_step.kind, 'recovery')
 		assert.equal(env.next_step.action, 'retry_rank')
 		assert.equal(env.next_step.context.clarification_turns_used, 1)
 		assert.equal(env.next_step.context.retry_count, 1)
+		assert.equal(env.meta.command, 'postlex')
+		assert.ok(env.meta.exit_code > 0, 'retry envelope must mirror a non-zero exit code')
 	})
 
 	it('increments retry_count on each call', () => {
@@ -344,8 +411,16 @@ describe('normalize_data_rows', () => {
 // ─── extract_data_array_from_search_output (v0.48.0) ──────────────────────
 
 describe('extract_data_array_from_search_output', () => {
-	it('extracts data.results from the canonical envelope shape', () => {
-		const env = { data: { query: 'q', mode: 'semantic', results: [{ name: 'foo' }] }, error: null, next_step: null }
+	it('extracts data.results from the canonical (spec 260525) envelope shape', () => {
+		// Canonical envelope: every key always an object, never null.
+		const env = {
+			ok: true,
+			data: { query: 'q', mode: 'semantic', results: [{ name: 'foo' }] },
+			error: {},
+			next_step: {},
+			warnings: [],
+			meta: { command: 'search', exit_code: 0, envelope_schema_version: '1.0.0' },
+		}
 		const r = extract_data_array_from_search_output(env)
 		assert.equal(r.length, 1)
 		assert.equal(r[0].name, 'foo')
@@ -380,9 +455,12 @@ describe('parse_input with --search-output', () => {
 	it('extracts data.results from a full search envelope passed as the third argument', () => {
 		const ranking = JSON.stringify({ ranking: [{ rank: 1, candidate_id: 1, rationale: 'top' }] })
 		const search_out = JSON.stringify({
+			ok: true,
 			data: { query: 'q', mode: 'semantic', results: [{ name: 'deploy-aws', workspace_slug: 'acme' }] },
-			error: null,
-			next_step: null,
+			error: {},
+			next_step: {},
+			warnings: [],
+			meta: { command: 'search', exit_code: 0, envelope_schema_version: '1.0.0' },
 		})
 		const r = parse_input(ranking, null, search_out)
 		assert.equal(r.parse_error, null)

package/src/commands/pull.js

@@ -125,7 +125,11 @@ const run = (args) => catch_errors('Pull failed', async () => {
 				next_step: result.next_step || null,
 				error: result.error || null
 			})
-			if (result.next_step) process.exit(EXIT_CODES.ERROR)
+			// Spec § 9.1 — exit code reflects whether the OPERATION succeeded,
+			// not whether a next_step is present. Success-with-followup (data
+			// populated, next_step set, error empty) is exit 0. A populated
+			// error is the signal for non-zero exit.
+			if (result.error && result.error.code) process.exit(EXIT_CODES.ERROR)
 			return
 		}
 		if (result.error) {

package/src/commands/reconcile.js

@@ -58,6 +58,52 @@ const resolve_lock_entry = (raw, project_root, is_global) => catch_errors('Faile
 	return { full, lock_entry, lock_data }
 })
 
+// Expand the internal { action, context: {...} } reconcile result into the
+// closed-enum six-key next_step shape (spec § 4.5 / § 7). Returns {} for
+// the no-followup case.
+const NEXT_STEP_INSTRUCTIONS = {
+	resolve_regression: 'Disk version is older than lock. Pick one of the listed options and re-run with --apply <option>.',
+	resolve_missing_skill_json: 'skill.json is missing. Pick one of the listed restore options and re-run with --apply <option>.',
+	resolve_missing_dir: 'The skill directory is missing. Pick one of the listed options and re-run with --apply <option>.',
+	install_first: 'Skill is not in the lock file. Install it first, then re-run reconcile.',
+}
+const NEXT_STEP_KINDS_MAP = {
+	resolve_regression:         'decision',
+	resolve_missing_skill_json: 'decision',
+	resolve_missing_dir:        'decision',
+	install_first:              'routing',
+}
+const enrich_reconcile_next_step = (ns, full) => {
+	if (!ns || typeof ns !== 'object') return {}
+	const action = ns.action
+	if (!action) return {}
+	const kind = NEXT_STEP_KINDS_MAP[action] || 'decision'
+	if (action === 'install_first') {
+		return {
+			kind,
+			action,
+			instructions: NEXT_STEP_INSTRUCTIONS.install_first,
+			context: { commands: [`npx happyskills install ${full} --json`] },
+			route_to_skill: 'happyskills',
+		}
+	}
+	const opts = ns.context?.options || []
+	return {
+		kind,
+		action,
+		instructions: NEXT_STEP_INSTRUCTIONS[action] || 'Pick one of the listed options and re-run.',
+		context: {
+			options: opts,
+			...(ns.context?.drift ? { drift: ns.context.drift } : {}),
+			commands: opts.length > 0
+				? [`npx happyskills reconcile ${full} --apply ${opts[0]} --json`]
+				: undefined,
+		},
+		principal_authorization_required: true,
+		route_to_skill: 'happyskills-sync',
+	}
+}
+
 const apply_restore_from_lock_version = ({ skill_dir, lock_entry }) => catch_errors('Failed to restore from lock', async () => {
 	const [read_err, manifest] = await read_manifest(skill_dir)
 	if (read_err) throw e('Failed to read skill.json', read_err)
@@ -197,10 +243,12 @@ const run = (args) => catch_errors('Reconcile failed', async () => {
 	if (recon_err) throw e('Reconcile failed', recon_err)
 
 	if (args.flags.json) {
-		const envelope = { data: result.data }
-		if (result.next_step !== undefined) envelope.next_step = result.next_step
-		if (result.hint !== undefined) envelope.hint = result.hint
-		print_json(envelope)
+		const { emit_envelope } = require('../ui/envelope')
+		// Inline the human-readable hint into data so the envelope's
+		// next_step slot remains reserved for actionable protocol followups.
+		const data = result.hint !== undefined ? { ...result.data, hint: result.hint } : result.data
+		const next_step = enrich_reconcile_next_step(result.next_step, full)
+		emit_envelope({ data, next_step })
 		return
 	}
 

package/src/commands/release.js

@@ -217,11 +217,14 @@ const orchestrate = (args) => catch_errors('Release failed', async () => {
 				drift: target_info.drift
 			}),
 			next_step: {
-				action: 'reconcile_first',
+				kind:         'recovery',
+				action:       'reconcile_first',
+				instructions: 'Drift must be resolved before release. Run reconcile, follow its next_step, then retry release.',
 				context: {
-					reconcile_command: `npx happyskills reconcile ${lock_key} --json`,
-					skill: lock_key
-				}
+					commands: [`npx happyskills reconcile ${lock_key} --json`],
+					skill:    lock_key,
+				},
+				route_to_skill: 'happyskills-sync',
 			}
 		})
 		return { code: EXIT_CODES.ERROR, envelope: restored }
@@ -229,14 +232,26 @@ const orchestrate = (args) => catch_errors('Release failed', async () => {
 	if (target_info.status === 'missing_version') {
 		const restored = await restore_and({
 			...envelope_error('MISSING_VERSION', '--no-bump was passed but disk is not ahead of lock; nothing to publish.'),
-			next_step: { action: 'specify_bump_type', context: { current_version: manifest.version } }
+			next_step: {
+				kind:         'decision',
+				action:       'specify_bump_type',
+				instructions: 'No target version determined. Pick a bump type and re-run.',
+				context:      { options: ['patch', 'minor', 'major'], current_version: manifest.version },
+				principal_authorization_required: true,
+			}
 		})
 		return { code: EXIT_CODES.USAGE, envelope: restored }
 	}
 	if (target_info.status === 'invalid_bump') {
 		const restored = await restore_and({
 			...envelope_error('INVALID_BUMP', `--bump "${target_info.bump}" is not patch/minor/major or a valid semver.`),
-			next_step: { action: 'specify_bump_type', context: { current_version: manifest.version } }
+			next_step: {
+				kind:         'decision',
+				action:       'specify_bump_type',
+				instructions: 'The bump value is not valid. Pick a bump type and re-run.',
+				context:      { options: ['patch', 'minor', 'major'], current_version: manifest.version, got: target_info.bump },
+				principal_authorization_required: true,
+			}
 		})
 		return { code: EXIT_CODES.USAGE, envelope: restored }
 	}
@@ -244,8 +259,11 @@ const orchestrate = (args) => catch_errors('Release failed', async () => {
 		const restored = await restore_and({
 			...envelope_error('MISSING_VERSION', 'No --bump provided and no CHANGELOG entry indicates an intended next version.'),
 			next_step: {
-				action: 'specify_bump_type',
-				context: { current_version: manifest.version, options: ['patch', 'minor', 'major', 'explicit-version'] }
+				kind:         'decision',
+				action:       'specify_bump_type',
+				instructions: 'No target version provided. Pick a bump type and re-run.',
+				context:      { options: ['patch', 'minor', 'major'], current_version: manifest.version },
+				principal_authorization_required: true,
 			}
 		})
 		return { code: EXIT_CODES.USAGE, envelope: restored }
@@ -254,12 +272,15 @@ const orchestrate = (args) => catch_errors('Release failed', async () => {
 		const restored = await restore_and({
 			...envelope_error('BUMP_DISAGREEMENT', `--bump ${target_info.requested_bump} disagrees with the disk version ${target_info.disk_version}.`),
 			next_step: {
-				action: 'resolve_bump_disagreement',
+				kind:         'decision',
+				action:       'resolve_bump_disagreement',
+				instructions: 'The --bump value disagrees with the disk version. Pick one and re-run.',
 				context: {
-					disk_version: target_info.disk_version,
+					disk_version:   target_info.disk_version,
 					requested_bump: target_info.requested_bump,
-					lock_version: target_info.lock_version
-				}
+					lock_version:   target_info.lock_version,
+				},
+				principal_authorization_required: true,
 			}
 		})
 		return { code: EXIT_CODES.USAGE, envelope: restored }
@@ -299,7 +320,13 @@ const orchestrate = (args) => catch_errors('Release failed', async () => {
 			if (cf_err || !cf_content) {
 				const restored = await restore_and({
 					...envelope_error('CHANGELOG_SOURCE_UNREADABLE', `Could not read --changelog-from "${changelog_from}".`),
-					next_step: { action: 'provide_changelog' }
+					next_step: {
+						kind:         'recovery',
+						action:       'provide_changelog',
+						instructions: 'The --changelog-from file could not be read. Provide a readable file and re-run.',
+						context:      {},
+						principal_authorization_required: true,
+					}
 				})
 				return { code: EXIT_CODES.USAGE, envelope: restored }
 			}
@@ -311,8 +338,11 @@ const orchestrate = (args) => catch_errors('Release failed', async () => {
 			const restored = await restore_and({
 				...envelope_error('MISSING_CHANGELOG_ENTRY', `CHANGELOG.md does not contain a ## [${target_version}] entry.`),
 				next_step: {
-					action: 'provide_changelog',
-					context: { target_version, current_top_entry: cl_top }
+					kind:         'recovery',
+					action:       'provide_changelog',
+					instructions: 'CHANGELOG.md is missing an entry for the target version. Add the entry and re-run release.',
+					context:      { target_version, current_top_entry: cl_top },
+					principal_authorization_required: true,
 				}
 			})
 			return { code: EXIT_CODES.USAGE, envelope: restored }