happyskills 0.53.0 → 1.0.0

package/src/integration/install_fresh.test.js

@@ -19,14 +19,21 @@ const { spawnSync } = require('child_process')
 const fs = require('fs')
 const os = require('os')
 const path = require('path')
+const {
+	parse_envelope,
+	assert_error_envelope,
+	assert_has_next_step,
+} = require('../schema/envelope_test_helpers')
 
 const CLI = path.resolve(__dirname, '../../bin/happyskills.js')
 const NODE = process.execPath
 
 const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-install-fresh-test-'))
 const run = (args, opts) => {
-	const result = spawnSync(NODE, [CLI, ...args], {
-		env: { ...process.env, NO_COLOR: '1', HAPPYSKILLS_API_URL: 'http://localhost:0', ...(opts?.env || {}) },
+	const has_mode_flag = args.includes('--json') || args.includes('--text')
+	const final_args = has_mode_flag ? args : [...args, '--text']
+	const result = spawnSync(NODE, [CLI, ...final_args], {
+		env: { ...process.env, NO_COLOR: '1', HAPPYSKILLS_ENVELOPE_STRICT: '1', HAPPYSKILLS_API_URL: 'http://localhost:0', CI: '', ...(opts?.env || {}) },
 		encoding: 'utf-8',
 		timeout: 10000,
 		cwd: opts?.cwd
@@ -93,50 +100,51 @@ const scaffold_installed = ({ full, short, version, modified }) => {
 }
 
 describe('install --fresh — § 8.5 hardening', () => {
-	it('hard-fails with VERSION_NOT_FOUND when registry is unreachable (no silent fallback)', async () => {
+	it('hard-fails with VERSION_NOT_FOUND envelope when registry is unreachable (no silent fallback)', async () => {
 		const ctx = await scaffold_installed({ full: 'acme/test', short: 'test', version: '1.0.0' })
 		try {
-			const { code, stderr, stdout } = run(
+			const { code, stdout } = run(
 				['install', 'acme/test@0.3.3', '--fresh', '--json', '-y'],
 				{ cwd: ctx.root }
 			)
-			// Exit code 2 (USER_ERROR) per spec § 8.5.
-			assert.strictEqual(code, 2, 'must exit with USER_ERROR (2), not silently succeed')
-			// Combined output must mention VERSION_NOT_FOUND.
-			const combined = stdout + stderr
-			assert.match(combined, /VERSION_NOT_FOUND/, 'must surface VERSION_NOT_FOUND, not silently fall back to latest')
-			// JSON envelope's error.code must be USAGE_ERROR (not bare ERROR) so
-			// downstream consumers can parse on the code rather than the message.
-			const json_match = stdout.match(/^{[\s\S]*}\s*$/m)
-			if (json_match) {
-				const parsed = JSON.parse(json_match[0])
-				assert.strictEqual(parsed.error?.code, 'USAGE_ERROR', `error.code must be USAGE_ERROR, got ${parsed.error?.code}`)
-			}
+			// Exit code 2 per spec § 5.3 mapping table (VERSION_NOT_FOUND → 2).
+			assert.strictEqual(code, 2, 'VERSION_NOT_FOUND maps to exit 2 per spec § 5.3')
+			const env = parse_envelope(stdout, 'install --fresh VERSION_NOT_FOUND')
+			assert_error_envelope(env, 'VERSION_NOT_FOUND', 'install --fresh missing version')
+			// Decision next_step: pick_version with available list + safe command.
+			assert_has_next_step(env, 'pick_version', 'install --fresh missing version')
+			assert.strictEqual(env.next_step.kind, 'decision')
+			assert.strictEqual(env.next_step.context.requested, '0.3.3')
+			assert.strictEqual(env.next_step.principal_authorization_required, true)
 
 			// Critical: disk content must be UNCHANGED — no silent overwrite.
 			assert.strictEqual(ctx.read_manifest().version, '1.0.0', 'skill.json must NOT have been overwritten')
 		} finally { ctx.cleanup() }
 	})
 
-	it('refuses --fresh when local edits are present unless --force-discard-local', async () => {
+	it('refuses --fresh when local edits are present, emitting LOCAL_EDITS_PRESENT + confirm_discard_or_snapshot_first', async () => {
 		const ctx = await scaffold_installed({ full: 'acme/edited', short: 'edited', version: '1.0.0', modified: true })
 		try {
-			const { code, stdout, stderr } = run(
+			const { code, stdout } = run(
 				['install', 'acme/edited@1.0.0', '--fresh', '--json', '-y'],
 				{ cwd: ctx.root }
 			)
-			// Should hard-fail at the LOCAL_EDITS_PRESENT step (before any registry call would matter).
 			assert.notStrictEqual(code, 0, 'must not succeed silently')
-			const combined = stdout + stderr
-			// Either LOCAL_EDITS_PRESENT (preferred, when registry is unreachable
-			// and we never get to the version check, we still expect LOCAL_EDITS
-			// to surface — but registry-failure currently runs first, surfacing
-			// VERSION_NOT_FOUND). Either way, NO silent overwrite must occur.
-			assert.ok(
-				/LOCAL_EDITS_PRESENT|VERSION_NOT_FOUND/.test(combined),
-				`must refuse to clobber local edits, got: ${combined}`
-			)
-			// The mutated content must still be on disk.
+			const env = parse_envelope(stdout, 'install --fresh LOCAL_EDITS_PRESENT')
+			// LOCAL_EDITS_PRESENT must surface BEFORE the registry-call failure
+			// path — the local-state gate is structurally earlier than the
+			// network call. Registry unreachability is irrelevant here.
+			assert_error_envelope(env, 'LOCAL_EDITS_PRESENT', 'install --fresh local edits')
+			assert_has_next_step(env, 'confirm_discard_or_snapshot_first', 'install --fresh local edits')
+			assert.strictEqual(env.next_step.kind, 'confirmation')
+			assert.strictEqual(env.next_step.principal_authorization_required, true)
+			// Commands array: SAFE default first (snapshot), destructive second.
+			const commands = env.next_step.context.commands
+			assert.ok(Array.isArray(commands) && commands.length >= 2)
+			assert.match(commands[0], /snapshot/, 'safe command (snapshot) must come first')
+			assert.match(commands[1], /--force-discard-local/, 'destructive variant second')
+
+			// The mutated content must still be on disk — confirmation gate held.
 			assert.ok(/MUTATED BODY/.test(ctx.read_skill_md()), 'local mutation must be preserved')
 		} finally { ctx.cleanup() }
 	})

package/src/integration/reconcile.test.js

@@ -1,14 +1,15 @@
 'use strict'
 /**
- * Integration tests for `happyskills reconcile` — § 8.4. The command's
- * single job: handle GENUINE drift (regression / missing_skill_json /
- * missing_dir / corrupted) deterministically when possible, emit next_step
- * envelopes when user adjudication is required, and **no-op on the `ahead`
- * state** (ahead is not drift; it routes back to publish).
+ * Integration tests for `happyskills reconcile` — § 8.4 + envelope refactor
+ * (spec 260525-cli-default-json). Asserts on the SIX-KEY envelope shape:
+ * top-level `ok / data / error / next_step / warnings / meta`, closed enums,
+ * dependentRequired clusters. Every --json invocation is validated via the
+ * shared parse_envelope helper so this file doubles as a conformance test.
  *
- * These tests prevent the spec § 17.7 anti-pattern from recurring — the
- * earlier draft auto-repaired `ahead` here, which was exactly the category
- * error that produced the § 2 incident.
+ * The other invariant locked here: reconcile NO-OPS on the `ahead` state.
+ * Ahead is not drift — it must produce a success envelope with NO populated
+ * next_step (next_step === {}), routing the agent back to publish through a
+ * data.hint or similar in-data signal, never via the envelope's next_step.
  */
 const { describe, it } = require('node:test')
 const assert = require('node:assert/strict')
@@ -16,24 +17,28 @@ const { spawnSync } = require('child_process')
 const fs = require('fs')
 const os = require('os')
 const path = require('path')
+const {
+	parse_envelope,
+	assert_success_envelope,
+	assert_has_next_step,
+	assert_no_next_step,
+} = require('../schema/envelope_test_helpers')
 
 const CLI = path.resolve(__dirname, '../../bin/happyskills.js')
 const NODE = process.execPath
 
 const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-reconcile-test-'))
 const run = (args, opts) => {
-	const result = spawnSync(NODE, [CLI, ...args], {
-		env: { ...process.env, NO_COLOR: '1', HAPPYSKILLS_API_URL: 'http://localhost:0', ...(opts?.env || {}) },
+	const has_mode_flag = args.includes('--json') || args.includes('--text')
+	const final_args = has_mode_flag ? args : [...args, '--text']
+	const result = spawnSync(NODE, [CLI, ...final_args], {
+		env: { ...process.env, NO_COLOR: '1', HAPPYSKILLS_ENVELOPE_STRICT: '1', HAPPYSKILLS_API_URL: 'http://localhost:0', CI: '', ...(opts?.env || {}) },
 		encoding: 'utf-8',
 		timeout: 10000,
 		cwd: opts?.cwd
 	})
 	return { stdout: result.stdout || '', stderr: result.stderr || '', code: result.status }
 }
-const parse_json = (stdout, label) => {
-	try { return JSON.parse(stdout) }
-	catch { assert.fail(`${label}: stdout is not valid JSON:\n${stdout}`) }
-}
 
 const scaffold = ({ full, short, lock_version, disk_version, omit_skill_json, omit_dir }) => {
 	const root = make_tmp()
@@ -77,33 +82,38 @@ const scaffold = ({ full, short, lock_version, disk_version, omit_skill_json, om
 	}
 }
 
-describe('reconcile — § 8.4', () => {
-	it('reports clean (no work to do) when lock and disk agree', () => {
+describe('reconcile — envelope shape (§ 8.4 + envelope refactor)', () => {
+	it('reports clean as a success envelope with no follow-up', () => {
 		const ctx = scaffold({ full: 'acme/clean', short: 'clean', lock_version: '1.0.0', disk_version: '1.0.0' })
 		try {
 			const { code, stdout } = run(['reconcile', 'acme/clean', '--json'], { cwd: ctx.root })
 			assert.strictEqual(code, 0)
-			const out = parse_json(stdout, 'reconcile clean')
-			assert.strictEqual(out.data.no_drift, true)
-			assert.strictEqual(out.data.status, 'clean')
-			assert.strictEqual(out.next_step, null)
+			const env = parse_envelope(stdout, 'reconcile clean')
+			assert_success_envelope(env, 'reconcile clean')
+			assert_no_next_step(env, 'reconcile clean')
+			assert.strictEqual(env.data.no_drift, true)
+			assert.strictEqual(env.data.status, 'clean')
+			assert.strictEqual(env.meta.command, 'reconcile')
 		} finally { ctx.cleanup() }
 	})
 
-	it('NO-OPS on ahead (disk > lock) — points back to publish, does NOT mutate', () => {
-		// This is the spec § 17.7 anti-pattern test: the earlier design
-		// auto-repaired ahead via revert-and-rebump. That behavior is rejected.
+	it('NO-OPS on ahead (disk > lock) — success envelope, empty next_step, hint inside data', () => {
+		// Spec § 17.7 anti-pattern guard: ahead is NOT drift. The envelope
+		// must reflect that with an empty next_step. The "go publish" hint
+		// lives inside data, never in the envelope.next_step slot (that
+		// would mis-signal a protocol followup).
 		const ctx = scaffold({ full: 'acme/ahead', short: 'ahead', lock_version: '0.3.2', disk_version: '0.3.3' })
 		try {
 			const { code, stdout } = run(['reconcile', 'acme/ahead', '--json'], { cwd: ctx.root })
 			assert.strictEqual(code, 0)
-			const out = parse_json(stdout, 'reconcile ahead')
-			assert.strictEqual(out.data.no_drift, true)
-			assert.strictEqual(out.data.status, 'ahead')
-			assert.strictEqual(out.data.ahead.lock_version, '0.3.2')
-			assert.strictEqual(out.data.ahead.disk_version, '0.3.3')
-			assert.strictEqual(out.next_step, null, 'must NOT emit a next_step for ahead — it is not drift')
-			assert.match(out.hint, /publish/i, 'hint should point at publish/release, not at repair')
+			const env = parse_envelope(stdout, 'reconcile ahead')
+			assert_success_envelope(env, 'reconcile ahead')
+			assert_no_next_step(env, 'reconcile ahead')
+			assert.strictEqual(env.data.no_drift, true)
+			assert.strictEqual(env.data.status, 'ahead')
+			assert.strictEqual(env.data.ahead.lock_version, '0.3.2')
+			assert.strictEqual(env.data.ahead.disk_version, '0.3.3')
+			assert.match(env.data.hint, /publish/i, 'hint inside data should point at publish/release')
 
 			// Confirm no file mutation.
 			assert.strictEqual(ctx.read_manifest().version, '0.3.3', 'skill.json must be unchanged')
@@ -111,29 +121,35 @@ describe('reconcile — § 8.4', () => {
 		} finally { ctx.cleanup() }
 	})
 
-	it('emits resolve_regression next_step for disk < lock', () => {
+	it('emits resolve_regression decision next_step for disk < lock', () => {
 		const ctx = scaffold({ full: 'acme/regression', short: 'regression', lock_version: '0.4.0', disk_version: '0.3.0' })
 		try {
 			const { code, stdout } = run(['reconcile', 'acme/regression', '--json'], { cwd: ctx.root })
+			// Diagnosis-with-followup is success — exit 0, but next_step populated.
 			assert.strictEqual(code, 0)
-			const out = parse_json(stdout, 'reconcile regression')
-			assert.strictEqual(out.data.drift_state, 'regression')
-			assert.ok(out.next_step)
-			assert.strictEqual(out.next_step.action, 'resolve_regression')
-			assert.ok(out.next_step.context.options.includes('restore_from_lock_version'))
-			assert.ok(out.next_step.context.options.includes('accept_disk_as_explicit_downgrade'))
+			const env = parse_envelope(stdout, 'reconcile regression')
+			assert_success_envelope(env, 'reconcile regression')
+			assert_has_next_step(env, 'resolve_regression', 'reconcile regression')
+			assert.strictEqual(env.next_step.kind, 'decision')
+			assert.strictEqual(env.next_step.principal_authorization_required, true)
+			assert.strictEqual(env.data.drift_state, 'regression')
+			assert.ok(env.next_step.context.options.includes('restore_from_lock_version'))
+			assert.ok(env.next_step.context.options.includes('accept_disk_as_explicit_downgrade'))
+			// Spec § 4.5.2: reconcile routes to happyskills-sync.
+			assert.strictEqual(env.next_step.route_to_skill, 'happyskills-sync')
 		} finally { ctx.cleanup() }
 	})
 
-	it('--apply restore_from_lock_version repairs a regression deterministically', () => {
+	it('--apply restore_from_lock_version repairs a regression and emits success with no follow-up', () => {
 		const ctx = scaffold({ full: 'acme/fix-regression', short: 'fix-regression', lock_version: '0.4.0', disk_version: '0.3.0' })
 		try {
 			const { code, stdout } = run(['reconcile', 'acme/fix-regression', '--apply', 'restore_from_lock_version', '--json'], { cwd: ctx.root })
 			assert.strictEqual(code, 0)
-			const out = parse_json(stdout, 'reconcile regression apply')
-			assert.strictEqual(out.data.applied.applied, 'restore_from_lock_version')
-			assert.strictEqual(out.data.applied.new_disk_version, '0.4.0')
-			assert.strictEqual(out.next_step, null)
+			const env = parse_envelope(stdout, 'reconcile regression apply')
+			assert_success_envelope(env, 'reconcile apply')
+			assert_no_next_step(env, 'reconcile apply')
+			assert.strictEqual(env.data.applied.applied, 'restore_from_lock_version')
+			assert.strictEqual(env.data.applied.new_disk_version, '0.4.0')
 
 			// skill.json now matches the lock.
 			assert.strictEqual(ctx.read_manifest().version, '0.4.0')
@@ -150,12 +166,14 @@ describe('reconcile — § 8.4', () => {
 		try {
 			const { code, stdout } = run(['reconcile', 'acme/no-manifest', '--json'], { cwd: ctx.root })
 			assert.strictEqual(code, 0)
-			const out = parse_json(stdout, 'reconcile missing-manifest')
-			assert.strictEqual(out.data.drift_state, 'missing_skill_json')
-			assert.strictEqual(out.next_step.action, 'resolve_missing_skill_json')
-			assert.ok(out.next_step.context.options.includes('restore_from_git'))
-			assert.ok(out.next_step.context.options.includes('restore_from_registry_at_lock_version'))
-			assert.ok(out.next_step.context.options.includes('abandon'))
+			const env = parse_envelope(stdout, 'reconcile missing-manifest')
+			assert_success_envelope(env, 'reconcile missing-manifest')
+			assert_has_next_step(env, 'resolve_missing_skill_json', 'reconcile missing-manifest')
+			assert.strictEqual(env.next_step.kind, 'decision')
+			assert.strictEqual(env.data.drift_state, 'missing_skill_json')
+			assert.ok(env.next_step.context.options.includes('restore_from_git'))
+			assert.ok(env.next_step.context.options.includes('restore_from_registry_at_lock_version'))
+			assert.ok(env.next_step.context.options.includes('abandon'))
 		} finally { ctx.cleanup() }
 	})
 
@@ -167,11 +185,13 @@ describe('reconcile — § 8.4', () => {
 		try {
 			const { code, stdout } = run(['reconcile', 'acme/no-dir', '--json'], { cwd: ctx.root })
 			assert.strictEqual(code, 0)
-			const out = parse_json(stdout, 'reconcile missing-dir')
-			assert.strictEqual(out.data.drift_state, 'missing_dir')
-			assert.strictEqual(out.next_step.action, 'resolve_missing_dir')
-			assert.ok(out.next_step.context.options.includes('reinstall_at_lock_version'))
-			assert.ok(out.next_step.context.options.includes('abandon'))
+			const env = parse_envelope(stdout, 'reconcile missing-dir')
+			assert_success_envelope(env, 'reconcile missing-dir')
+			assert_has_next_step(env, 'resolve_missing_dir', 'reconcile missing-dir')
+			assert.strictEqual(env.next_step.kind, 'decision')
+			assert.strictEqual(env.data.drift_state, 'missing_dir')
+			assert.ok(env.next_step.context.options.includes('reinstall_at_lock_version'))
+			assert.ok(env.next_step.context.options.includes('abandon'))
 		} finally { ctx.cleanup() }
 	})
 
@@ -180,9 +200,10 @@ describe('reconcile — § 8.4', () => {
 		try {
 			const { code, stdout } = run(['reconcile', 'bare', '--json'], { cwd: ctx.root })
 			assert.strictEqual(code, 0)
-			const out = parse_json(stdout, 'reconcile bare')
-			assert.strictEqual(out.data.skill, 'acme/bare')
-			assert.strictEqual(out.data.no_drift, true)
+			const env = parse_envelope(stdout, 'reconcile bare')
+			assert_success_envelope(env)
+			assert.strictEqual(env.data.skill, 'acme/bare')
+			assert.strictEqual(env.data.no_drift, true)
 		} finally { ctx.cleanup() }
 	})
 })

package/src/integration/release.test.js

@@ -1,12 +1,14 @@
 'use strict'
 /**
- * Integration tests for `happyskills release` — § 8.2.
+ * Integration tests for `happyskills release` — § 8.2 + envelope refactor
+ * (spec 260525-cli-default-json). Asserts on the six-key envelope shape and
+ * the closed `next_step.action` enum.
  *
  * Focus: the failure-mode envelopes (drift, missing_version, missing_changelog
  * entry) and the ahead-recognition path through --dry-run. The full happy-path
- * publish requires a real registry and is covered by the existing publish
- * pipeline tests; here we verify orchestration, snapshot capture/restore, and
- * the structured next_step envelopes.
+ * publish requires a real registry and is covered by the publish pipeline
+ * tests; here we verify orchestration, snapshot capture/restore, and the
+ * structured next_step envelopes.
  */
 const { describe, it } = require('node:test')
 const assert = require('node:assert/strict')
@@ -14,24 +16,28 @@ const { spawnSync } = require('child_process')
 const fs = require('fs')
 const os = require('os')
 const path = require('path')
+const {
+	parse_envelope,
+	assert_success_envelope,
+	assert_error_envelope,
+	assert_has_next_step,
+} = require('../schema/envelope_test_helpers')
 
 const CLI = path.resolve(__dirname, '../../bin/happyskills.js')
 const NODE = process.execPath
 
 const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-release-test-'))
 const run = (args, opts) => {
-	const result = spawnSync(NODE, [CLI, ...args], {
-		env: { ...process.env, NO_COLOR: '1', HAPPYSKILLS_API_URL: 'http://localhost:0', ...(opts?.env || {}) },
+	const has_mode_flag = args.includes('--json') || args.includes('--text')
+	const final_args = has_mode_flag ? args : [...args, '--text']
+	const result = spawnSync(NODE, [CLI, ...final_args], {
+		env: { ...process.env, NO_COLOR: '1', HAPPYSKILLS_ENVELOPE_STRICT: '1', HAPPYSKILLS_API_URL: 'http://localhost:0', CI: '', ...(opts?.env || {}) },
 		encoding: 'utf-8',
 		timeout: 15000,
 		cwd: opts?.cwd
 	})
 	return { stdout: result.stdout || '', stderr: result.stderr || '', code: result.status }
 }
-const parse_json = (stdout, label) => {
-	try { return JSON.parse(stdout) }
-	catch { assert.fail(`${label}: stdout is not valid JSON:\n${stdout}`) }
-}
 
 const scaffold = ({ full, short, lock_version, disk_version, changelog }) => {
 	const root = make_tmp()
@@ -81,7 +87,7 @@ const scaffold = ({ full, short, lock_version, disk_version, changelog }) => {
 }
 
 describe('release — orchestration envelopes', () => {
-	it('blocks on regression drift and routes to reconcile', () => {
+	it('blocks on regression drift and routes to reconcile via recovery next_step', () => {
 		const ctx = scaffold({
 			full: 'acme/regressed', short: 'regressed',
 			lock_version: '1.0.0', disk_version: '0.9.0'
@@ -89,10 +95,15 @@ describe('release — orchestration envelopes', () => {
 		try {
 			const { code, stdout } = run(['release', 'regressed', '--workspace', 'acme', '--json'], { cwd: ctx.root })
 			assert.notStrictEqual(code, 0)
-			const env = parse_json(stdout, 'release regressed')
-			assert.strictEqual(env.error.code, 'DRIFT_DETECTED')
-			assert.strictEqual(env.next_step.action, 'reconcile_first')
-			assert.match(env.next_step.context.reconcile_command, /reconcile/)
+			const env = parse_envelope(stdout, 'release regressed')
+			assert_error_envelope(env, 'DRIFT_DETECTED', 'release regressed')
+			assert_has_next_step(env, 'reconcile_first', 'release regressed')
+			assert.strictEqual(env.next_step.kind, 'recovery')
+			// Recovery commands array carries the verbatim follow-up command(s).
+			assert.ok(Array.isArray(env.next_step.context.commands))
+			assert.ok(env.next_step.context.commands.some(c => /reconcile/.test(c)))
+			// Drift detail propagates through error.drift.
+			assert.strictEqual(env.error.drift.reason, 'regression')
 		} finally { ctx.cleanup() }
 	})
 
@@ -105,7 +116,8 @@ describe('release — orchestration envelopes', () => {
 		try {
 			const { code, stdout } = run(['release', 'ahead-dry', '--workspace', 'acme', '--dry-run', '--json'], { cwd: ctx.root })
 			assert.strictEqual(code, 0, 'dry-run on ahead must succeed')
-			const env = parse_json(stdout, 'release ahead dry-run')
+			const env = parse_envelope(stdout, 'release ahead dry-run')
+			assert_success_envelope(env, 'release ahead dry-run')
 			assert.strictEqual(env.data.dry_run, true)
 			assert.strictEqual(env.data.target_version, '0.3.3')
 			assert.strictEqual(env.data.ahead_recognized, true)
@@ -115,7 +127,7 @@ describe('release — orchestration envelopes', () => {
 		} finally { ctx.cleanup() }
 	})
 
-	it('blocks with MISSING_VERSION on clean + --no-bump', () => {
+	it('blocks with MISSING_VERSION + specify_bump_type on clean + --no-bump', () => {
 		const ctx = scaffold({
 			full: 'acme/clean', short: 'clean',
 			lock_version: '1.0.0', disk_version: '1.0.0'
@@ -123,8 +135,11 @@ describe('release — orchestration envelopes', () => {
 		try {
 			const { code, stdout } = run(['release', 'clean', '--workspace', 'acme', '--no-bump', '--json'], { cwd: ctx.root })
 			assert.notStrictEqual(code, 0)
-			const env = parse_json(stdout, 'release clean --no-bump')
-			assert.strictEqual(env.error.code, 'MISSING_VERSION')
+			const env = parse_envelope(stdout, 'release clean --no-bump')
+			assert_error_envelope(env, 'MISSING_VERSION', 'release clean --no-bump')
+			assert_has_next_step(env, 'specify_bump_type', 'release missing version')
+			assert.strictEqual(env.next_step.kind, 'decision')
+			assert.deepStrictEqual(env.next_step.context.options, ['patch', 'minor', 'major'])
 		} finally { ctx.cleanup() }
 	})
 
@@ -137,13 +152,15 @@ describe('release — orchestration envelopes', () => {
 		try {
 			const { code, stdout } = run(['release', 'no-cl', '--bump', 'patch', '--workspace', 'acme', '--json'], { cwd: ctx.root })
 			assert.notStrictEqual(code, 0)
-			const env = parse_json(stdout, 'release no-cl')
-			assert.strictEqual(env.error.code, 'MISSING_CHANGELOG_ENTRY')
-			assert.strictEqual(env.next_step.action, 'provide_changelog')
+			const env = parse_envelope(stdout, 'release no-cl')
+			assert_error_envelope(env, 'MISSING_CHANGELOG_ENTRY', 'release no-cl')
+			assert_has_next_step(env, 'provide_changelog', 'release no-cl')
+			assert.strictEqual(env.next_step.kind, 'recovery')
+			assert.strictEqual(env.next_step.principal_authorization_required, true)
 		} finally { ctx.cleanup() }
 	})
 
-	it('emits bump_disagreement when --bump value contradicts an already-ahead disk', () => {
+	it('emits BUMP_DISAGREEMENT + resolve_bump_disagreement when --bump contradicts an already-ahead disk', () => {
 		const ctx = scaffold({
 			full: 'acme/disagree', short: 'disagree',
 			lock_version: '0.1.0', disk_version: '0.5.0'
@@ -151,19 +168,19 @@ describe('release — orchestration envelopes', () => {
 		try {
 			const { code, stdout } = run(['release', 'disagree', '--bump', 'patch', '--workspace', 'acme', '--json'], { cwd: ctx.root })
 			assert.notStrictEqual(code, 0)
-			const env = parse_json(stdout, 'release disagree')
-			assert.strictEqual(env.error.code, 'BUMP_DISAGREEMENT')
-			assert.strictEqual(env.next_step.action, 'resolve_bump_disagreement')
+			const env = parse_envelope(stdout, 'release disagree')
+			assert_error_envelope(env, 'BUMP_DISAGREEMENT', 'release disagree')
+			assert_has_next_step(env, 'resolve_bump_disagreement', 'release disagree')
+			assert.strictEqual(env.next_step.kind, 'decision')
 			assert.strictEqual(env.next_step.context.disk_version, '0.5.0')
+			assert.strictEqual(env.next_step.context.requested_bump, 'patch')
 		} finally { ctx.cleanup() }
 	})
 
 	it('§2 scenario re-test: ahead state ends in a successful dry-run with NO revert and NO drift error', () => {
 		// This is the canonical regression test for the original failure.
 		// Setup mirrors §2 exactly: lock 0.3.2, disk 0.3.3 (hand-edited bump),
-		// CHANGELOG already has the 0.3.3 entry. The full publish would need
-		// a real registry — but the orchestration must reach the publish
-		// step cleanly, not block on a misclassified drift error.
+		// CHANGELOG already has the 0.3.3 entry.
 		const ctx = scaffold({
 			full: 'happyskillsai/happyskills-help', short: 'happyskills-help',
 			lock_version: '0.3.2', disk_version: '0.3.3',
@@ -172,11 +189,11 @@ describe('release — orchestration envelopes', () => {
 		try {
 			const { code, stdout } = run(['release', 'happyskills-help', '--workspace', 'happyskillsai', '--dry-run', '--json'], { cwd: ctx.root })
 			assert.strictEqual(code, 0, '§2 scenario must NOT block — ahead is normal authoring')
-			const env = parse_json(stdout, '§2 scenario re-test')
+			const env = parse_envelope(stdout, '§2 scenario re-test')
+			assert_success_envelope(env, '§2 scenario re-test')
 			assert.strictEqual(env.data.dry_run, true)
 			assert.strictEqual(env.data.target_version, '0.3.3', 'must publish the disk version')
 			assert.strictEqual(env.data.ahead_recognized, true)
-			// Snapshot was created and (because dry-run) restored — disk must be unchanged.
 			assert.strictEqual(ctx.read_manifest().version, '0.3.3')
 		} finally { ctx.cleanup() }
 	})