happyskills 0.53.0 → 1.0.0

package/src/commands/search.test.js

@@ -1,12 +1,36 @@
 // Unit tests for the next_step envelope emission rules on
-// cli/src/commands/search.js. Spec 260521-01 v2 § 5.1.
+// cli/src/commands/search.js. Spec 260521-01 v2 § 5.1 + spec
+// 260525-cli-default-json § 4.5 / § 7.
 //
-// The orchestration around the actual HTTP call is covered by manual E2E
-// testing (spec § 7); here we lock down the pure decision logic.
+// Locked envelope contract: build_search_next_step returns either {} (no
+// follow-up) or a populated three-key object { kind, action, instructions }
+// plus optional context / principal_authorization_required / route_to_skill.
+// Action names come from the closed enum (NEXT_STEP_ACTIONS); the legacy
+// short names (`clarify`, `present_to_user` alone) no longer apply where the
+// new enum supersedes them.
 
 const { describe, it } = require('node:test')
 const assert = require('node:assert/strict')
 const { build_search_next_step } = require('./search')
+const {
+	NEXT_STEP_KINDS,
+	NEXT_STEP_ACTIONS,
+	kind_for_action,
+} = require('../constants/next_step_actions')
+
+const is_empty = (o) => o && typeof o === 'object' && !Array.isArray(o) && Object.keys(o).length === 0
+
+const assert_envelope_next_step = (ns, expected_action, label) => {
+	assert.ok(ns && typeof ns === 'object', `${label}: next_step must be an object`)
+	if (expected_action === null) {
+		assert.ok(is_empty(ns), `${label}: expected empty {} next_step, got ${JSON.stringify(ns)}`)
+		return
+	}
+	assert.strictEqual(ns.action, expected_action, `${label}: action mismatch`)
+	assert.ok(NEXT_STEP_KINDS.includes(ns.kind), `${label}: kind "${ns.kind}" not in closed enum`)
+	assert.strictEqual(ns.kind, kind_for_action(expected_action), `${label}: kind must match action's kind`)
+	assert.ok(typeof ns.instructions === 'string' && ns.instructions.length > 0, `${label}: instructions must be non-empty`)
+}
 
 const make_response = (overrides = {}) => ({
 	mode:          'semantic',
@@ -17,38 +41,38 @@ const make_response = (overrides = {}) => ({
 	...overrides,
 })
 
-describe('build_search_next_step', () => {
-	it('returns null when --with-rerank is not set', () => {
+describe('build_search_next_step — envelope shape', () => {
+	it('returns empty {} when --with-rerank is not set', () => {
 		const r = build_search_next_step(make_response({ rerank_digests: [{ candidate_id: 1 }] }), 'q', {
 			with_rerank:                 false,
 			clarification_turns_used:    0,
 		})
-		assert.equal(r, null)
+		assert_envelope_next_step(r, null, 'with_rerank=false')
 	})
 
-	it('returns null when mode is fuzzy_slug (no rerank for non-semantic modes)', () => {
+	it('returns empty {} when mode is fuzzy_slug (no rerank for non-semantic modes)', () => {
 		const r = build_search_next_step(make_response({ mode: 'fuzzy_slug' }), 'q', {
 			with_rerank: true, clarification_turns_used: 0,
 		})
-		assert.equal(r, null)
+		assert_envelope_next_step(r, null, 'fuzzy_slug')
 	})
 
-	it('returns null when mode is fuzzy_scoped', () => {
+	it('returns empty {} when mode is fuzzy_scoped', () => {
 		const r = build_search_next_step(make_response({ mode: 'fuzzy_scoped' }), 'q', {
 			with_rerank: true, clarification_turns_used: 0,
 		})
-		assert.equal(r, null)
+		assert_envelope_next_step(r, null, 'fuzzy_scoped')
 	})
 
-	it('emits rank_digests_inline when semantic mode + digests present', () => {
+	it('emits rank_digests_inline (kind=continuation) when semantic + digests present', () => {
 		const r = build_search_next_step(make_response({
 			rerank_digests: [{ candidate_id: 1, digest: '...' }, { candidate_id: 2, digest: '...' }],
 		}), 'deploy aws', {
 			with_rerank: true, clarification_turns_used: 0,
 		})
-		assert.equal(r.action, 'rank_digests_inline')
-		assert.equal(r.context.original_query, 'deploy aws')
-		assert.equal(r.context.clarification_turns_used, 0)
+		assert_envelope_next_step(r, NEXT_STEP_ACTIONS.RANK_DIGESTS_INLINE, 'rank inline')
+		assert.strictEqual(r.context.original_query, 'deploy aws')
+		assert.strictEqual(r.context.clarification_turns_used, 0)
 		assert.match(r.instructions, /happyskills postlex/)
 		// Instructions should carry the budget forward to the next call.
 		assert.match(r.instructions, /--clarification-turns-used 0/)
@@ -58,65 +82,67 @@ describe('build_search_next_step', () => {
 		const r = build_search_next_step(make_response({
 			rerank_digests: [{ candidate_id: 1 }],
 		}), 'q', { with_rerank: true, clarification_turns_used: 1 })
+		assert_envelope_next_step(r, NEXT_STEP_ACTIONS.RANK_DIGESTS_INLINE, 'rank inline with budget')
 		assert.match(r.instructions, /--clarification-turns-used 1/)
-		assert.equal(r.context.clarification_turns_used, 1)
+		assert.strictEqual(r.context.clarification_turns_used, 1)
 	})
 
-	it('emits clarify when semantic + no digests + match_notice fires + budget remains', () => {
+	it('emits clarify_query (kind=clarification) when semantic + no digests + match_notice + budget remains', () => {
 		const r = build_search_next_step(make_response({
 			match_notice: 'No strong or good matches.',
 		}), 'vague query', { with_rerank: true, clarification_turns_used: 0 })
-		assert.equal(r.action, 'clarify')
-		assert.equal(r.max_turns_remaining, 2)
-		// Always last option is "Just search anyway".
-		const opts = r.suggested_questions[0].options
+		assert_envelope_next_step(r, NEXT_STEP_ACTIONS.CLARIFY_QUERY, 'clarify')
+		// suggested_questions and max_turns_remaining now live INSIDE context.
+		assert.strictEqual(r.context.max_turns_remaining, 2)
+		assert.ok(Array.isArray(r.context.suggested_questions))
+		const opts = r.context.suggested_questions[0].options
 		assert.match(opts[opts.length - 1].label, /search anyway/i)
+		assert.strictEqual(r.principal_authorization_required, true)
 		// Instructions carry the incremented budget forward.
 		assert.match(r.instructions, /--clarification-turns-used 1/)
 	})
 
-	it('emits present_to_user (budget spent) when match_notice fires AND turns_used >= 2', () => {
+	it('emits present_to_user (kind=continuation) when match_notice fires AND turns_used >= 2', () => {
 		const r = build_search_next_step(make_response({
 			match_notice: 'No strong or good matches.',
 		}), 'q', { with_rerank: true, clarification_turns_used: 2 })
-		assert.equal(r.action, 'present_to_user')
+		assert_envelope_next_step(r, NEXT_STEP_ACTIONS.PRESENT_TO_USER, 'budget spent')
 		assert.match(r.instructions, /budget.*spent/i)
 	})
 
-	it('returns null when semantic + no digests + no match_notice (no protocol applies)', () => {
+	it('returns empty {} when semantic + no digests + no match_notice (no protocol applies)', () => {
 		const r = build_search_next_step(make_response(), 'q', {
 			with_rerank: true, clarification_turns_used: 0,
 		})
-		assert.equal(r, null)
+		assert_envelope_next_step(r, null, 'no protocol applies')
 	})
 
 	it('treats empty rerank_digests array as "no digests"', () => {
 		const r = build_search_next_step(make_response({ rerank_digests: [] }), 'q', {
 			with_rerank: true, clarification_turns_used: 0,
 		})
-		// No digests → would clarify if notice fired; here no notice, so null.
-		assert.equal(r, null)
+		assert_envelope_next_step(r, null, 'empty digests')
 	})
 
 	it('clamps clarification_turns_used to [0, 2]', () => {
 		const r_neg = build_search_next_step(make_response({ match_notice: 'weak' }), 'q', {
 			with_rerank: true, clarification_turns_used: -5,
 		})
-		assert.equal(r_neg.max_turns_remaining, 2)
+		assert.strictEqual(r_neg.context.max_turns_remaining, 2)
 		const r_big = build_search_next_step(make_response({ match_notice: 'weak' }), 'q', {
 			with_rerank: true, clarification_turns_used: 99,
 		})
-		assert.equal(r_big.action, 'present_to_user')
+		assert_envelope_next_step(r_big, NEXT_STEP_ACTIONS.PRESENT_TO_USER, 'budget overflow')
 	})
 
-	it('the clarify suggested_questions always includes 4 options ending in "Just search anyway"', () => {
+	it('the clarify_query context.suggested_questions always includes 4 options ending in "Just search anyway"', () => {
 		const r = build_search_next_step(make_response({ match_notice: 'weak' }), 'q', {
 			with_rerank: true, clarification_turns_used: 0,
 		})
-		assert.equal(r.suggested_questions.length, 1)
-		const opts = r.suggested_questions[0].options
-		assert.equal(opts.length, 4)
+		assert.strictEqual(r.context.suggested_questions.length, 1)
+		const opts = r.context.suggested_questions[0].options
+		assert.strictEqual(opts.length, 4)
 		assert.match(opts[3].label, /search anyway/i)
-		assert.equal(opts[3].refined_query_hint, null)
+		assert.strictEqual(opts[3].refined_query_hint, null)
 	})
 })

package/src/commands/uninstall.js

@@ -69,17 +69,26 @@ const run = (args) => catch_errors('Uninstall failed', async () => {
 	}
 
 	if (args.flags.json) {
-		const items = results.map(({ skill, result }) => ({
-			skill,
-			removed: result.removed || [],
-			orphans_pruned: result.orphans_pruned || []
-		}))
-		const data = results.length === 1 && failures.length === 0 ? items[0] : items
-		if (failures.length > 0) {
-			print_json({ data, errors: failures })
-		} else {
-			print_json({ data })
-		}
+		// Spec 260525-cli-default-json § 4.3 rules 2 + 4:
+		//   - No shape-flipping between single and batch — always emit
+		//     `data.results: [...]` so skills iterate uniformly.
+		//   - Per-row failures live inside `data.results[i].error`, not at
+		//     the envelope root (top-level `error` is reserved for
+		//     whole-operation failures).
+		const items = [
+			...results.map(({ skill, result }) => ({
+				skill,
+				status: 'uninstalled',
+				removed: result.removed || [],
+				orphans_pruned: result.orphans_pruned || []
+			})),
+			...failures.map(({ skill, error }) => ({
+				skill,
+				status: 'failed',
+				error: { code: 'INTERNAL_ERROR', message: error }
+			}))
+		]
+		print_json({ data: { results: items } })
 		return
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })

package/src/commands/validate.js

@@ -96,17 +96,39 @@ const format_json = (skill_name, all_results) => {
 	const failed = all_results.filter(r => r.severity === 'error')
 	const warned = all_results.filter(r => r.severity === 'warning')
 
-	print_json({
-		data: {
-			skill: skill_name,
-			valid: failed.length === 0,
-			errors,
-			warnings,
-			checks_passed: passed.length,
-			checks_failed: failed.length,
-			checks_warned: warned.length
-		}
-	})
+	const { emit_envelope } = require('../ui/envelope')
+	const { ERROR_CODES } = require('../constants/error_codes')
+	const data = {
+		skill: skill_name,
+		valid: failed.length === 0,
+		errors,
+		warnings,
+		checks_passed: passed.length,
+		checks_failed: failed.length,
+		checks_warned: warned.length,
+	}
+	if (failed.length > 0) {
+		emit_envelope({
+			data,
+			error: {
+				code:    ERROR_CODES.VALIDATION_FAILED,
+				message: `Validation failed: ${failed.length} error${failed.length === 1 ? '' : 's'}.`,
+				validation_errors: errors,
+			},
+			next_step: {
+				kind:         'recovery',
+				action:       'fix_validation_errors',
+				instructions: 'Fix the listed validation errors and re-run.',
+				context: {
+					validation_errors: errors,
+					commands: [`npx happyskills validate ${skill_name} --json`],
+				},
+			},
+			meta_overrides: { exit_code: 1 },
+		})
+		return
+	}
+	emit_envelope({ data })
 }
 
 const run = (args) => catch_errors('Validate failed', async () => {

package/src/constants/error_codes.js

@@ -0,0 +1,197 @@
+'use strict'
+// Closed enum of error codes emitted by the CLI envelope. Mirrors spec
+// 260525-cli-default-json § 5. Skeleton-only — Session 2 wires it into
+// emit_envelope / exit_with_error. Until then, only the test suite consumes
+// it (via envelope_validator).
+//
+// Renaming a code is a breaking envelope-schema change. Adding a code is
+// non-breaking. Removing a code is breaking.
+//
+// In Session 2 a publish-time copy step keeps this file byte-identical to
+// api/app/constants/error_codes.js. For Session 1b they evolve in lockstep
+// by inspection.
+
+// Auth & permission ────────────────────────────────────────────────────────
+const AUTH_REQUIRED          = 'AUTH_REQUIRED'
+const INVALID_CREDENTIALS    = 'INVALID_CREDENTIALS'
+const EXPIRED_TOKEN          = 'EXPIRED_TOKEN'
+const INTERACTIVE_REQUIRED   = 'INTERACTIVE_REQUIRED'
+const FORBIDDEN              = 'FORBIDDEN'
+const INSUFFICIENT_ACCESS    = 'INSUFFICIENT_ACCESS'
+const LAST_OWNER             = 'LAST_OWNER'
+const ORG_RESTRICTED         = 'ORG_RESTRICTED'
+
+// Network & transient ──────────────────────────────────────────────────────
+const NETWORK_ERROR          = 'NETWORK_ERROR'
+const RATE_LIMITED           = 'RATE_LIMITED'
+const DB_UNAVAILABLE         = 'DB_UNAVAILABLE'
+const GITHUB_UNAVAILABLE     = 'GITHUB_UNAVAILABLE'
+const EMBEDDING_UNAVAILABLE  = 'EMBEDDING_UNAVAILABLE'
+const REGISTRY_UNAVAILABLE   = 'REGISTRY_UNAVAILABLE'
+
+// Validation — input ───────────────────────────────────────────────────────
+const USAGE_ERROR            = 'USAGE_ERROR'
+const INVALID_BODY           = 'INVALID_BODY'
+const INVALID_SLUG           = 'INVALID_SLUG'
+const INVALID_VERSION        = 'INVALID_VERSION'
+const INVALID_BUMP           = 'INVALID_BUMP'
+const INVALID_NAME           = 'INVALID_NAME'
+const INVALID_PARAM          = 'INVALID_PARAM'
+const INVALID_VALUE          = 'INVALID_VALUE'
+const INVALID_VISIBILITY     = 'INVALID_VISIBILITY'
+const INVALID_PERMISSION     = 'INVALID_PERMISSION'
+const INVALID_ROLE           = 'INVALID_ROLE'
+const INVALID_SCOPE          = 'INVALID_SCOPE'
+const INVALID_STATE          = 'INVALID_STATE'
+const INVALID_STATUS         = 'INVALID_STATUS'
+const INVALID_OPERATION      = 'INVALID_OPERATION'
+const INVALID_CATEGORY       = 'INVALID_CATEGORY'
+const INVALID_FILTER         = 'INVALID_FILTER'
+const MISSING_FIELDS         = 'MISSING_FIELDS'
+
+// Validation — semantic ────────────────────────────────────────────────────
+const VALIDATION_FAILED              = 'VALIDATION_FAILED'
+const DEPENDENCY_VALIDATION_FAILED   = 'DEPENDENCY_VALIDATION_FAILED'
+const MISSING_CHANGELOG_ENTRY        = 'MISSING_CHANGELOG_ENTRY'
+const CHANGELOG_SOURCE_UNREADABLE    = 'CHANGELOG_SOURCE_UNREADABLE'
+
+// State & lifecycle ────────────────────────────────────────────────────────
+const NOT_FOUND                  = 'NOT_FOUND'
+const ALREADY_EXISTS             = 'ALREADY_EXISTS'
+const VERSION_EXISTS             = 'VERSION_EXISTS'
+const VERSION_NOT_FOUND          = 'VERSION_NOT_FOUND'
+const CONFLICT                   = 'CONFLICT'
+const DIVERGED                   = 'DIVERGED'
+const DRIFT_DETECTED             = 'DRIFT_DETECTED'
+const LOCAL_EDITS_PRESENT        = 'LOCAL_EDITS_PRESENT'
+const MISSING_VERSION            = 'MISSING_VERSION'
+const BUMP_DISAGREEMENT          = 'BUMP_DISAGREEMENT'
+const SLUG_TAKEN                 = 'SLUG_TAKEN'
+const RESOLUTION_FAILED          = 'RESOLUTION_FAILED'
+const REGISTRY_INTEGRITY_FAILURE = 'REGISTRY_INTEGRITY_FAILURE'
+const FORK_PARENT_NOT_FOUND      = 'FORK_PARENT_NOT_FOUND'
+const WORKSPACE_UNRESOLVED       = 'WORKSPACE_UNRESOLVED'
+const WORKSPACE_NOT_FOUND        = 'WORKSPACE_NOT_FOUND'
+
+// Confirmation ─────────────────────────────────────────────────────────────
+const CONFIRMATION_REQUIRED        = 'CONFIRMATION_REQUIRED'
+const DEPENDENCY_CASCADE_REQUIRED  = 'DEPENDENCY_CASCADE_REQUIRED'
+
+// Size limits ──────────────────────────────────────────────────────────────
+const PAYLOAD_TOO_LARGE              = 'PAYLOAD_TOO_LARGE'
+const FILE_TOO_LARGE                 = 'FILE_TOO_LARGE'
+const BODY_TOO_LONG                  = 'BODY_TOO_LONG'
+const SUBJECT_TOO_LONG               = 'SUBJECT_TOO_LONG'
+const ATTACHMENT_TOO_LARGE           = 'ATTACHMENT_TOO_LARGE'
+const TOTAL_ATTACHMENTS_TOO_LARGE    = 'TOTAL_ATTACHMENTS_TOO_LARGE'
+const ATTACHMENT_LIMIT_REACHED       = 'ATTACHMENT_LIMIT_REACHED'
+const CLIENT_CONTEXT_TOO_LARGE       = 'CLIENT_CONTEXT_TOO_LARGE'
+
+// GitHub / OAuth ───────────────────────────────────────────────────────────
+const GITHUB_NOT_LINKED       = 'GITHUB_NOT_LINKED'
+const GITHUB_ALREADY_LINKED   = 'GITHUB_ALREADY_LINKED'
+const CANNOT_UNLINK           = 'CANNOT_UNLINK'
+const NO_GITHUB_MAPPING       = 'NO_GITHUB_MAPPING'
+const CLAIM_EXPIRED           = 'CLAIM_EXPIRED'
+const NO_PENDING_CLAIM        = 'NO_PENDING_CLAIM'
+const ALREADY_CLAIMED         = 'ALREADY_CLAIMED'
+
+// Device flow ──────────────────────────────────────────────────────────────
+// Emitted by /auth/device/token on HTTP 202 polls (spec § 15.3.2). Not a
+// terminal failure — paired with a recovery next_step (action: retry).
+const AUTHORIZATION_PENDING   = 'AUTHORIZATION_PENDING'
+
+// CLI-only ─────────────────────────────────────────────────────────────────
+const COMMAND_NOT_FOUND         = 'COMMAND_NOT_FOUND'
+const MIN_CLI_VERSION           = 'MIN_CLI_VERSION'
+const SNAPSHOT_FAILED           = 'SNAPSHOT_FAILED'
+const WRITE_FAILED              = 'WRITE_FAILED'
+const PUBLISH_FAILED            = 'PUBLISH_FAILED'
+const RANKING_SCHEMA_MISMATCH   = 'RANKING_SCHEMA_MISMATCH'
+
+// Internal ─────────────────────────────────────────────────────────────────
+const INTERNAL_ERROR        = 'INTERNAL_ERROR'
+const PERSIST_FAILED        = 'PERSIST_FAILED'
+const VERIFICATION_FAILED   = 'VERIFICATION_FAILED'
+
+// Domain-specific codes used by API routes (additive — spec § 5 allows
+// non-breaking additions). Grouped by route family.
+// Auth / GitHub flows
+const NO_COGNITO_USER         = 'NO_COGNITO_USER'
+const COGNITO_SYNC_FAILED     = 'COGNITO_SYNC_FAILED'
+const COGNITO_UNLINK_FAILED   = 'COGNITO_UNLINK_FAILED'
+const ALREADY_HAS_PASSWORD    = 'ALREADY_HAS_PASSWORD'
+const EMAIL_ALIAS_CONFLICT    = 'EMAIL_ALIAS_CONFLICT'
+const ALREADY_APPROVED        = 'ALREADY_APPROVED'
+// Membership / access
+const ALREADY_MEMBER          = 'ALREADY_MEMBER'
+const ALREADY_COLLABORATOR    = 'ALREADY_COLLABORATOR'
+const DEPENDENCY_ACCESS_DENIED = 'DEPENDENCY_ACCESS_DENIED'
+const GROUP_NAME_TAKEN        = 'GROUP_NAME_TAKEN'
+const GROUP_ALREADY_GRANTED   = 'GROUP_ALREADY_GRANTED'
+// Body / params
+const BODY_REQUIRED           = 'BODY_REQUIRED'
+const FORBIDDEN_FIELD         = 'FORBIDDEN_FIELD'
+const INVALID_BYTES           = 'INVALID_BYTES'
+const INVALID_CONTENT_TYPE    = 'INVALID_CONTENT_TYPE'
+const INVALID_EVENT           = 'INVALID_EVENT'
+const INVALID_PARENTS         = 'INVALID_PARENTS'
+const TOO_MANY                = 'TOO_MANY'
+// Uploads
+const INVALID_UPLOAD_ID       = 'INVALID_UPLOAD_ID'
+const UPLOAD_NOT_FOUND        = 'UPLOAD_NOT_FOUND'
+// Listing / discovery
+const NOT_COMMUNITY_LISTED    = 'NOT_COMMUNITY_LISTED'
+
+// Forward-compat escape hatch (§ 5.2) ──────────────────────────────────────
+const UNKNOWN_CODE          = 'UNKNOWN_CODE'
+
+const ERROR_CODES = Object.freeze({
+	AUTH_REQUIRED, INVALID_CREDENTIALS, EXPIRED_TOKEN, INTERACTIVE_REQUIRED,
+	FORBIDDEN, INSUFFICIENT_ACCESS, LAST_OWNER, ORG_RESTRICTED,
+	NETWORK_ERROR, RATE_LIMITED, DB_UNAVAILABLE, GITHUB_UNAVAILABLE,
+	EMBEDDING_UNAVAILABLE, REGISTRY_UNAVAILABLE,
+	USAGE_ERROR, INVALID_BODY, INVALID_SLUG, INVALID_VERSION, INVALID_BUMP,
+	INVALID_NAME, INVALID_PARAM, INVALID_VALUE, INVALID_VISIBILITY,
+	INVALID_PERMISSION, INVALID_ROLE, INVALID_SCOPE, INVALID_STATE,
+	INVALID_STATUS, INVALID_OPERATION, INVALID_CATEGORY, INVALID_FILTER,
+	MISSING_FIELDS,
+	VALIDATION_FAILED, DEPENDENCY_VALIDATION_FAILED, MISSING_CHANGELOG_ENTRY,
+	CHANGELOG_SOURCE_UNREADABLE,
+	NOT_FOUND, ALREADY_EXISTS, VERSION_EXISTS, VERSION_NOT_FOUND, CONFLICT,
+	DIVERGED, DRIFT_DETECTED, LOCAL_EDITS_PRESENT, MISSING_VERSION,
+	BUMP_DISAGREEMENT, SLUG_TAKEN, RESOLUTION_FAILED,
+	REGISTRY_INTEGRITY_FAILURE, FORK_PARENT_NOT_FOUND, WORKSPACE_UNRESOLVED,
+	WORKSPACE_NOT_FOUND,
+	CONFIRMATION_REQUIRED, DEPENDENCY_CASCADE_REQUIRED,
+	PAYLOAD_TOO_LARGE, FILE_TOO_LARGE, BODY_TOO_LONG, SUBJECT_TOO_LONG,
+	ATTACHMENT_TOO_LARGE, TOTAL_ATTACHMENTS_TOO_LARGE,
+	ATTACHMENT_LIMIT_REACHED, CLIENT_CONTEXT_TOO_LARGE,
+	GITHUB_NOT_LINKED, GITHUB_ALREADY_LINKED, CANNOT_UNLINK, NO_GITHUB_MAPPING,
+	CLAIM_EXPIRED, NO_PENDING_CLAIM, ALREADY_CLAIMED,
+	AUTHORIZATION_PENDING,
+	COMMAND_NOT_FOUND, MIN_CLI_VERSION, SNAPSHOT_FAILED, WRITE_FAILED,
+	PUBLISH_FAILED, RANKING_SCHEMA_MISMATCH,
+	INTERNAL_ERROR, PERSIST_FAILED, VERIFICATION_FAILED,
+	NO_COGNITO_USER, COGNITO_SYNC_FAILED, COGNITO_UNLINK_FAILED,
+	ALREADY_HAS_PASSWORD, EMAIL_ALIAS_CONFLICT, ALREADY_APPROVED,
+	ALREADY_MEMBER, ALREADY_COLLABORATOR, DEPENDENCY_ACCESS_DENIED,
+	GROUP_NAME_TAKEN, GROUP_ALREADY_GRANTED,
+	BODY_REQUIRED, FORBIDDEN_FIELD, INVALID_BYTES, INVALID_CONTENT_TYPE,
+	INVALID_EVENT, INVALID_PARENTS, TOO_MANY,
+	INVALID_UPLOAD_ID, UPLOAD_NOT_FOUND, NOT_COMMUNITY_LISTED,
+	UNKNOWN_CODE,
+})
+
+const ERROR_CODE_LIST = Object.freeze(Object.values(ERROR_CODES).slice().sort())
+const ERROR_CODE_SET  = new Set(ERROR_CODE_LIST)
+
+const is_error_code = (s) => ERROR_CODE_SET.has(s)
+
+module.exports = {
+	ERROR_CODES,
+	ERROR_CODE_LIST,
+	ERROR_CODE_SET,
+	is_error_code,
+	...ERROR_CODES,
+}

package/src/constants/exit_codes.js

@@ -0,0 +1,54 @@
+'use strict'
+// EXIT_CODE_BY_ERROR table — spec 260525-cli-default-json § 5.3.
+// Maps each closed error.code to its process exit code. Codes not in the
+// table default to exit 1 (general error). Adding a new error_code without
+// adding it here is intentional: most domain failures map to 1.
+
+const EXIT_CODE_BY_ERROR = Object.freeze({
+	// Exit 2 — usage / input validation
+	USAGE_ERROR:           2,
+	COMMAND_NOT_FOUND:     2,
+	INVALID_BODY:          2,
+	INVALID_SLUG:          2,
+	INVALID_VERSION:       2,
+	INVALID_BUMP:          2,
+	INVALID_NAME:          2,
+	INVALID_PARAM:         2,
+	INVALID_VALUE:         2,
+	INVALID_VISIBILITY:    2,
+	INVALID_PERMISSION:    2,
+	INVALID_ROLE:          2,
+	INVALID_SCOPE:         2,
+	INVALID_STATE:         2,
+	INVALID_STATUS:        2,
+	INVALID_OPERATION:     2,
+	INVALID_CATEGORY:      2,
+	INVALID_FILTER:        2,
+	MISSING_FIELDS:        2,
+	MISSING_VERSION:       2,
+	WORKSPACE_UNRESOLVED:  2,
+	VERSION_NOT_FOUND:     2,
+
+	// Exit 3 — auth
+	AUTH_REQUIRED:         3,
+	INVALID_CREDENTIALS:   3,
+	EXPIRED_TOKEN:         3,
+	INTERACTIVE_REQUIRED:  3,
+
+	// Exit 4 — network / transient
+	NETWORK_ERROR:         4,
+	RATE_LIMITED:          4,
+	DB_UNAVAILABLE:        4,
+	GITHUB_UNAVAILABLE:    4,
+	EMBEDDING_UNAVAILABLE: 4,
+	REGISTRY_UNAVAILABLE:  4,
+
+	// All other codes default to exit 1.
+})
+
+const exit_code_for_error = (code) => {
+	if (!code) return 0
+	return EXIT_CODE_BY_ERROR[code] || 1
+}
+
+module.exports = { EXIT_CODE_BY_ERROR, exit_code_for_error }

package/src/constants/next_step_actions.js

@@ -0,0 +1,133 @@
+'use strict'
+// Closed enum of next_step actions and kinds emitted by the CLI envelope.
+// Mirrors spec 260525-cli-default-json § 6 + § 7. Skeleton-only — Session 2
+// wires it into the envelope builders. Until then, only the test suite
+// consumes it (via envelope_validator).
+//
+// Renaming or removing an action is BREAKING. Adding one is non-breaking.
+
+// Kinds (§ 6 — six closed values) ──────────────────────────────────────────
+const RECOVERY      = 'recovery'
+const CLARIFICATION = 'clarification'
+const DECISION      = 'decision'
+const CONFIRMATION  = 'confirmation'
+const CONTINUATION  = 'continuation'
+const ROUTING       = 'routing'
+
+const NEXT_STEP_KINDS = Object.freeze([
+	RECOVERY, CLARIFICATION, DECISION, CONFIRMATION, CONTINUATION, ROUTING,
+])
+const NEXT_STEP_KIND_SET = new Set(NEXT_STEP_KINDS)
+
+// Actions, grouped by kind (§ 7.1) ─────────────────────────────────────────
+
+// kind: recovery
+const LOGIN                    = 'login'
+const RETRY                    = 'retry'
+const RECONCILE_FIRST          = 'reconcile_first'
+const PULL_REBASE_FIRST        = 'pull_rebase_first'
+const FIX_VALIDATION_ERRORS    = 'fix_validation_errors'
+const PROVIDE_CHANGELOG        = 'provide_changelog'
+const SELF_UPDATE              = 'self_update'
+const SHOW_FORMAT              = 'show_format'
+const RETRY_RANK               = 'retry_rank'
+
+// kind: clarification
+const CLARIFY_QUERY            = 'clarify_query'
+
+// kind: decision
+const RESOLVE_REGRESSION             = 'resolve_regression'
+const RESOLVE_MISSING_SKILL_JSON     = 'resolve_missing_skill_json'
+const RESOLVE_MISSING_DIR            = 'resolve_missing_dir'
+const RESOLVE_CONFLICTS              = 'resolve_conflicts'
+const RESOLVE_PATCH_REJECTIONS       = 'resolve_patch_rejections'
+const SPECIFY_WORKSPACE              = 'specify_workspace'
+const SPECIFY_BUMP_TYPE              = 'specify_bump_type'
+const RESOLVE_BUMP_DISAGREEMENT      = 'resolve_bump_disagreement'
+const PICK_VERSION                   = 'pick_version'
+
+// kind: confirmation
+const CONFIRM_DISCARD_OR_SNAPSHOT_FIRST = 'confirm_discard_or_snapshot_first'
+const CONFIRM_CASCADE                   = 'confirm_cascade'
+const CONFIRM_DESTRUCTIVE               = 'confirm_destructive'
+const PASS_YES_FLAG                     = 'pass_yes_flag'
+
+// kind: continuation
+const RANK_DIGESTS_INLINE      = 'rank_digests_inline'
+const PRESENT_TO_USER          = 'present_to_user'
+const ATTACH_SCREENSHOT        = 'attach_screenshot'   // § 15.3.4
+
+// kind: routing
+const INSTALL_FIRST            = 'install_first'
+
+// kind lookup ──────────────────────────────────────────────────────────────
+const ACTION_KIND = Object.freeze({
+	[LOGIN]:                              RECOVERY,
+	[RETRY]:                              RECOVERY,
+	[RECONCILE_FIRST]:                    RECOVERY,
+	[PULL_REBASE_FIRST]:                  RECOVERY,
+	[FIX_VALIDATION_ERRORS]:              RECOVERY,
+	[PROVIDE_CHANGELOG]:                  RECOVERY,
+	[SELF_UPDATE]:                        RECOVERY,
+	[SHOW_FORMAT]:                        RECOVERY,
+	[RETRY_RANK]:                         RECOVERY,
+
+	[CLARIFY_QUERY]:                      CLARIFICATION,
+
+	[RESOLVE_REGRESSION]:                 DECISION,
+	[RESOLVE_MISSING_SKILL_JSON]:         DECISION,
+	[RESOLVE_MISSING_DIR]:                DECISION,
+	[RESOLVE_CONFLICTS]:                  DECISION,
+	[RESOLVE_PATCH_REJECTIONS]:           DECISION,
+	[SPECIFY_WORKSPACE]:                  DECISION,
+	[SPECIFY_BUMP_TYPE]:                  DECISION,
+	[RESOLVE_BUMP_DISAGREEMENT]:          DECISION,
+	[PICK_VERSION]:                       DECISION,
+
+	[CONFIRM_DISCARD_OR_SNAPSHOT_FIRST]:  CONFIRMATION,
+	[CONFIRM_CASCADE]:                    CONFIRMATION,
+	[CONFIRM_DESTRUCTIVE]:                CONFIRMATION,
+	[PASS_YES_FLAG]:                      CONFIRMATION,
+
+	[RANK_DIGESTS_INLINE]:                CONTINUATION,
+	[PRESENT_TO_USER]:                    CONTINUATION,
+	[ATTACH_SCREENSHOT]:                  CONTINUATION,
+
+	[INSTALL_FIRST]:                      ROUTING,
+})
+
+const NEXT_STEP_ACTIONS = Object.freeze({
+	LOGIN, RETRY, RECONCILE_FIRST, PULL_REBASE_FIRST, FIX_VALIDATION_ERRORS,
+	PROVIDE_CHANGELOG, SELF_UPDATE, SHOW_FORMAT, RETRY_RANK,
+	CLARIFY_QUERY,
+	RESOLVE_REGRESSION, RESOLVE_MISSING_SKILL_JSON, RESOLVE_MISSING_DIR,
+	RESOLVE_CONFLICTS, RESOLVE_PATCH_REJECTIONS, SPECIFY_WORKSPACE,
+	SPECIFY_BUMP_TYPE, RESOLVE_BUMP_DISAGREEMENT, PICK_VERSION,
+	CONFIRM_DISCARD_OR_SNAPSHOT_FIRST, CONFIRM_CASCADE, CONFIRM_DESTRUCTIVE,
+	PASS_YES_FLAG,
+	RANK_DIGESTS_INLINE, PRESENT_TO_USER, ATTACH_SCREENSHOT,
+	INSTALL_FIRST,
+})
+
+const NEXT_STEP_ACTION_LIST = Object.freeze(Object.values(NEXT_STEP_ACTIONS).slice().sort())
+const NEXT_STEP_ACTION_SET  = new Set(NEXT_STEP_ACTION_LIST)
+
+const is_next_step_action = (s) => NEXT_STEP_ACTION_SET.has(s)
+const is_next_step_kind   = (s) => NEXT_STEP_KIND_SET.has(s)
+const kind_for_action     = (a) => ACTION_KIND[a] || null
+
+module.exports = {
+	NEXT_STEP_KINDS,
+	NEXT_STEP_KIND_SET,
+	NEXT_STEP_ACTIONS,
+	NEXT_STEP_ACTION_LIST,
+	NEXT_STEP_ACTION_SET,
+	ACTION_KIND,
+	is_next_step_action,
+	is_next_step_kind,
+	kind_for_action,
+	// kind constants
+	RECOVERY, CLARIFICATION, DECISION, CONFIRMATION, CONTINUATION, ROUTING,
+	// action constants
+	...NEXT_STEP_ACTIONS,
+}