happyskills 0.46.1 → 0.47.1

package/src/commands/postlex.test.js

@@ -0,0 +1,303 @@
+// Unit tests for the pure logic inside cli/src/commands/postlex.js.
+// Spec 260521-01 v2 § 7 — the implementation is correct when:
+//   - ranking with no exact match → unchanged
+//   - exact at rank 2 → promoted to rank 1
+//   - exact already at rank 1 → unchanged
+//   - exact at rank 11 → unchanged (outside top-10 window)
+//   - malformed JSON input → envelope with next_step.action === "retry_rank"
+//   - out-of-bounds candidate_id → warned + dropped, not a crash
+
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const {
+	validate_ranking,
+	apply_postlex,
+	build_final_ordering,
+	determine_next_step,
+	build_retry_envelope,
+	parse_input,
+} = require('./postlex')
+
+// ─── Test fixtures ────────────────────────────────────────────────────────
+
+const make_data = (names) => names.map((name, i) => ({
+	name,
+	workspace_slug: 'acme',
+	description:    `desc for ${name}`,
+	match_quality:  i === 0 ? 'strong' : i === 1 ? 'good' : 'partial',
+	star_count:     10 - i,
+	quality_score:  80 - i * 10,
+}))
+
+const make_ranking = (ids) => ids.map((cid, i) => ({
+	rank:         i + 1,
+	candidate_id: cid,
+	rationale:    `rationale for ${cid}`,
+}))
+
+// ─── apply_postlex ────────────────────────────────────────────────────────
+
+describe('apply_postlex', () => {
+	it('returns ranking unchanged when no exact slug match exists in top-10', () => {
+		const data = make_data(['deploy-aws-lambda', 'serverless-framework', 'static-hosting'])
+		const ranking = make_ranking([1, 2, 3])
+		const r = apply_postlex('totally-different-query', ranking, data)
+		assert.equal(r.promoted, false)
+		assert.equal(r.promoted_from_rank, null)
+		assert.equal(r.exact_match_count_in_window, 0)
+		assert.deepEqual(r.reordered.map(x => x.candidate_id), [1, 2, 3])
+	})
+
+	it('promotes exact slug match from rank 2 → rank 1', () => {
+		const data = make_data(['serverless-framework', 'deploy-aws', 'static-hosting'])
+		const ranking = make_ranking([1, 2, 3])
+		const r = apply_postlex('deploy aws', ranking, data)
+		assert.equal(r.promoted, true)
+		assert.equal(r.promoted_from_rank, 2)
+		assert.equal(r.exact_match_count_in_window, 1)
+		// Now candidate_id=2 (the deploy-aws row) should be at rank 1.
+		assert.equal(r.reordered[0].candidate_id, 2)
+		assert.equal(r.reordered[0].rank, 1)
+		// Ranks should be reassigned 1..N.
+		assert.deepEqual(r.reordered.map(x => x.rank), [1, 2, 3])
+	})
+
+	it('leaves ranking unchanged when exact match is already at rank 1', () => {
+		const data = make_data(['deploy-aws', 'serverless', 'static'])
+		const ranking = make_ranking([1, 2, 3])
+		const r = apply_postlex('deploy aws', ranking, data)
+		assert.equal(r.promoted, false)
+		assert.equal(r.exact_match_count_in_window, 1)
+		assert.deepEqual(r.reordered.map(x => x.candidate_id), [1, 2, 3])
+	})
+
+	it('ignores exact match outside the top-10 window', () => {
+		const names = []
+		for (let i = 1; i <= 11; i++) names.push(i === 11 ? 'deploy-aws' : `other-${i}`)
+		const data = make_data(names)
+		// rank the 11 candidates 1..11, deploy-aws (candidate_id=11) is at rank 11
+		const ranking = make_ranking(Array.from({ length: 11 }, (_, i) => i + 1))
+		const r = apply_postlex('deploy aws', ranking, data)
+		assert.equal(r.promoted, false)
+		assert.equal(r.exact_match_count_in_window, 0)
+		// Top-10 window doesn't include rank 11 → no promotion.
+	})
+
+	it('when multiple exact matches exist, promotes the highest-ranked one', () => {
+		const data = make_data(['other', 'deploy-aws', 'something', 'deploy-aws-2'])
+		// Both rank 2 (candidate 2) and rank 4 (candidate 4) are exact for "deploy aws"
+		// because slug_tokens drops the trailing "2" (single-char skip).
+		// candidate_id=2 has rank=2; candidate_id=4 has rank=4.
+		// The algorithm picks the highest-ranked one (smallest rank value).
+		const ranking = make_ranking([1, 2, 3, 4])
+		const r = apply_postlex('deploy aws', ranking, data)
+		assert.equal(r.promoted, true)
+		assert.equal(r.promoted_from_rank, 2)
+		assert.equal(r.reordered[0].candidate_id, 2)
+	})
+})
+
+// ─── validate_ranking ─────────────────────────────────────────────────────
+
+describe('validate_ranking', () => {
+	const data = make_data(['a', 'b', 'c'])
+
+	it('accepts well-formed entries', () => {
+		const r = validate_ranking(make_ranking([1, 2, 3]), data)
+		assert.equal(r.valid_items.length, 3)
+		assert.equal(r.dropped.length, 0)
+	})
+
+	it('drops candidate_id < 1', () => {
+		const r = validate_ranking([{ rank: 1, candidate_id: 0 }], data)
+		assert.equal(r.valid_items.length, 0)
+		assert.equal(r.dropped.length, 1)
+		assert.match(r.dropped[0].reason, /out of range/)
+	})
+
+	it('drops candidate_id > data.length', () => {
+		const r = validate_ranking([{ rank: 1, candidate_id: 99 }], data)
+		assert.equal(r.valid_items.length, 0)
+		assert.match(r.dropped[0].reason, /out of range/)
+	})
+
+	it('drops candidate_id that is not an integer', () => {
+		const r = validate_ranking([{ rank: 1, candidate_id: 'banana' }], data)
+		assert.equal(r.valid_items.length, 0)
+		assert.match(r.dropped[0].reason, /out of range/)
+	})
+
+	it('drops entries where data row is missing name', () => {
+		const broken_data = [{ name: '' }, { name: 'real' }]
+		const r = validate_ranking([{ rank: 1, candidate_id: 1 }, { rank: 2, candidate_id: 2 }], broken_data)
+		assert.equal(r.valid_items.length, 1)
+		assert.equal(r.dropped[0].candidate_id, 1)
+		assert.match(r.dropped[0].reason, /missing name/)
+	})
+
+	it('rejects non-array ranking', () => {
+		const r = validate_ranking({ not: 'an array' }, data)
+		assert.equal(r.valid_items.length, 0)
+		assert.equal(r.dropped.length, 1)
+	})
+
+	it('rejects non-array data', () => {
+		const r = validate_ranking([{ rank: 1, candidate_id: 1 }], { not: 'an array' })
+		assert.equal(r.valid_items.length, 0)
+	})
+
+	it('keeps some, drops some — mixed batch', () => {
+		const r = validate_ranking([
+			{ rank: 1, candidate_id: 1 },
+			{ rank: 2, candidate_id: 99 },  // out of range
+			{ rank: 3, candidate_id: 2 },
+		], data)
+		assert.equal(r.valid_items.length, 2)
+		assert.equal(r.dropped.length, 1)
+	})
+})
+
+// ─── determine_next_step ──────────────────────────────────────────────────
+
+describe('determine_next_step', () => {
+	const fo = (qualities) => qualities.map((q, i) => ({
+		rank:           i + 1,
+		candidate_id:   i + 1,
+		slug:           `acme/r-${i}`,
+		name:           `r-${i}`,
+		match_quality:  q,
+		rationale:      '',
+	}))
+
+	it('emits present_to_user 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')
+	})
+
+	it('emits clarify 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.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]
+		assert.match(last.label, /search anyway/i)
+	})
+
+	it('emits clarify 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)
+	})
+
+	it('emits present_to_user with budget-spent note when budget exhausted', () => {
+		const ns = determine_next_step(fo(['weak', 'partial', null]), 'q', 2)
+		assert.equal(ns.action, 'present_to_user')
+		assert.match(ns.instructions, /budget.*spent/i)
+	})
+
+	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)
+		const ns_big = determine_next_step(fo(['partial', 'partial', 'partial']), 'q', 99)
+		assert.equal(ns_big.action, 'present_to_user')
+	})
+
+	it('emits present_to_user when ordering is empty (no results to clarify against)', () => {
+		const ns = determine_next_step([], 'q', 0)
+		assert.equal(ns.action, 'present_to_user')
+	})
+
+	it('treats top-1-and-only-1 strong as success (less than 3 results)', () => {
+		const ns = determine_next_step(fo(['strong']), 'q', 0)
+		assert.equal(ns.action, 'present_to_user')
+	})
+})
+
+// ─── build_retry_envelope ─────────────────────────────────────────────────
+
+describe('build_retry_envelope', () => {
+	it('produces a retry_rank envelope with all required fields', () => {
+		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)
+		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)
+	})
+
+	it('increments retry_count on each call', () => {
+		const env1 = build_retry_envelope('q', 'r', 0, 0)
+		const env2 = build_retry_envelope('q', 'r', 0, env1.next_step.context.retry_count)
+		assert.equal(env2.next_step.context.retry_count, 2)
+	})
+})
+
+// ─── parse_input ──────────────────────────────────────────────────────────
+
+describe('parse_input', () => {
+	it('parses combined ranking+data from a single JSON object', () => {
+		const raw = JSON.stringify({
+			ranking: [{ rank: 1, candidate_id: 1 }],
+			data:    [{ name: 'foo' }],
+		})
+		const r = parse_input(raw, null)
+		assert.equal(r.parse_error, null)
+		assert.equal(r.ranking[0].candidate_id, 1)
+		assert.equal(r.data[0].name, 'foo')
+	})
+
+	it('parses separate ranking + data files', () => {
+		const ranking_raw = JSON.stringify({ ranking: [{ rank: 1, candidate_id: 1 }] })
+		const data_raw    = JSON.stringify({ data:    [{ name: 'foo' }] })
+		const r = parse_input(ranking_raw, data_raw)
+		assert.equal(r.parse_error, null)
+		assert.equal(r.ranking.length, 1)
+		assert.equal(r.data[0].name, 'foo')
+	})
+
+	it('accepts bare arrays in either file', () => {
+		const r = parse_input(JSON.stringify([{ rank: 1, candidate_id: 1 }]), JSON.stringify([{ name: 'foo' }]))
+		assert.equal(r.parse_error, null)
+		assert.equal(r.ranking.length, 1)
+		assert.equal(r.data.length, 1)
+	})
+
+	it('returns parse_error on malformed JSON', () => {
+		const r = parse_input('this is not json at all', null)
+		assert.equal(r.ranking, null)
+		assert.match(r.parse_error, /not valid JSON/)
+	})
+
+	it('returns parse_error when ranking is missing from single-payload input', () => {
+		const r = parse_input(JSON.stringify({ data: [] }), null)
+		assert.match(r.parse_error, /ranking field is missing/)
+	})
+
+	it('returns parse_error when data is missing entirely', () => {
+		const r = parse_input(JSON.stringify({ ranking: [] }), null)
+		assert.match(r.parse_error, /data field is missing/)
+	})
+})
+
+// ─── build_final_ordering ─────────────────────────────────────────────────
+
+describe('build_final_ordering', () => {
+	it('joins ranking with data rows, producing slug + rationale', () => {
+		const data = make_data(['deploy-aws', 'serverless'])
+		const ranking = make_ranking([1, 2])
+		const ordered = build_final_ordering(ranking, data)
+		assert.equal(ordered.length, 2)
+		assert.equal(ordered[0].slug, 'acme/deploy-aws')
+		assert.equal(ordered[0].rationale, 'rationale for 1')
+		assert.equal(ordered[0].match_quality, 'strong')
+	})
+
+	it('uses bare name when workspace_slug is absent', () => {
+		const data = [{ name: 'lone-skill', match_quality: 'good' }]
+		const ordered = build_final_ordering([{ rank: 1, candidate_id: 1, rationale: '' }], data)
+		assert.equal(ordered[0].slug, 'lone-skill')
+		assert.equal(ordered[0].workspace_slug, null)
+	})
+})

package/src/commands/search.js

@@ -5,6 +5,7 @@ const { bold, dim, yellow, cyan, gray } = require('../ui/colors')
 const { exit_with_error, UsageError, AuthError } = require('../utils/errors')
 const { EXIT_CODES, VALID_SKILL_TYPES } = require('../constants')
 const { load_token } = require('../auth/token_store')
+const { fire_discovery_telemetry } = require('../api/telemetry')
 
 const HELP_TEXT = `Usage: happyskills search [query] [options]
 
@@ -23,6 +24,12 @@ Options:
   --tags <tags>           Filter by tags (comma-separated)
   --type <type>           Filter by type (skill, kit)
   --exact                 Force keyword-only FTS matching (skip smart routing)
+  --with-rerank           Include rerank digests + next_step envelope in --json output
+                          (intended for use inside an agentic session — see the
+                           happyskills-help skill's discovery-protocol reference)
+  --clarification-turns-used <N>
+                          Clarification budget already spent (0-2, default 0).
+                          Carried across re-searches in the clarification flow.
   --limit <n>             Max results (required, 1-50)
   --min-quality <n>       Minimum quality score 0-100
   --json                  Output as JSON
@@ -112,16 +119,90 @@ const to_smart_json = (item) => ({
 	updated_at: item.updated_at,
 })
 
+// Spec 260521-01 v2 § 5.1 — build the next_step envelope for a search response.
+// Pure function: takes the response state + clarification budget + flags and
+// returns either a NextStep object or null. Exported for testing.
+const STRONG_TIERS = new Set(['strong', 'good'])
+
+const build_search_next_step = (response, query, opts) => {
+	const { with_rerank, clarification_turns_used } = opts
+	if (!with_rerank) return null
+
+	const mode = response?.mode || null
+	const digests = Array.isArray(response?.rerank_digests) ? response.rerank_digests : null
+	const match_notice = response?.match_notice || null
+	const turns_used = Math.max(0, Math.min(2, clarification_turns_used | 0))
+	const turns_remaining = 2 - turns_used
+
+	// Non-semantic modes (slug, scoped, exact-FTS) don't support rerank — server
+	// returns no digests. No envelope; agent just renders.
+	if (mode !== 'semantic') return null
+
+	// Semantic + digests present → the protocol's primary path.
+	if (digests && digests.length > 0) {
+		return {
+			action:       'rank_digests_inline',
+			instructions: `Rank these candidates by how well their \`digest\` matches the query, using \`data.rerank_system_prompt\` as your system instructions. Emit JSON matching \`data.rerank_response_schema\`. Aim for ~20 items (10-30 acceptable; fewer if remaining candidates aren't clearly differentiated). Then pipe the result to \`npx happyskills postlex --query "${query}" --ranking - --clarification-turns-used ${turns_used}\`.`,
+			context: {
+				original_query:           query,
+				clarification_turns_used: turns_used,
+			},
+		}
+	}
+
+	// Semantic + no digests + match_notice fires → clarify path (when budget
+	// remains) OR present_to_user with budget-spent note.
+	if (match_notice) {
+		if (turns_remaining <= 0) {
+			return {
+				action:       'present_to_user',
+				instructions: 'No top result is a strong match and the clarification budget (2 turns) is spent. Render `data.results` honestly: note the weak signal and present what you have so the user can decide. Do NOT ask another clarifying question.',
+				context:      null,
+			}
+		}
+		return {
+			action: 'clarify',
+			instructions: `The search returned weak results. Ask the user one of \`suggested_questions\` using your agent's question mechanism, then re-run \`npx happyskills search "<refined query>" --with-rerank --json --limit 50 --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: 'Quick clarification — what specifically are you looking for?',
+					options: [
+						{ label: 'A workflow or how-to guide',                       refined_query_hint: 'workflow' },
+						{ label: 'A specific tool or library',                       refined_query_hint: 'tool' },
+						{ label: 'A platform-specific recipe (AWS / GCP / Vercel)',  refined_query_hint: 'platform' },
+						{ label: 'Just search anyway',                               refined_query_hint: null },
+					],
+				},
+			],
+			max_turns_remaining: turns_remaining,
+			context: {
+				original_query:           query,
+				clarification_turns_used: turns_used,
+			},
+		}
+	}
+
+	// Semantic, no digests, no match_notice (defensive — shouldn't normally
+	// happen). Agent renders the baseline results.
+	return null
+}
+
 const run_smart_search = (args, query, options) => catch_errors('Smart search failed', async () => {
 	const limit = parseInt(args.flags.limit)
 	const capped_limit = Math.min(Math.max(limit, 1), 50)
 	const min_quality = args.flags['min-quality'] != null ? parseInt(args.flags['min-quality']) : null
+	const with_rerank = !!args.flags['with-rerank']
+	const clarification_turns_used = parseInt(args.flags['clarification-turns-used'] || '0', 10) || 0
 
 	const search_opts = { ...options, limit: capped_limit }
+	if (with_rerank) search_opts.with_rerank_digests = true
+
 	const [errors, response] = await repos_api.dispatch_search(query, search_opts)
 	if (errors) throw e('Search failed', errors)
 
-	// Response shape: { data: [...], mode, workspace_match, match_notice }
+	// Response shape: { data: [...], mode, workspace_match, match_notice,
+	//   and when with_rerank_digests=true: rerank_digests, rerank_system_prompt,
+	//   rerank_prompt_version, rerank_response_schema }
 	const items_raw = Array.isArray(response) ? response : (response?.data || response?.repos || response?.items || [])
 	let items = items_raw
 	const mode = response?.mode || null
@@ -135,12 +216,46 @@ const run_smart_search = (args, query, options) => catch_errors('Smart search fa
 		)
 	}
 
+	const next_step = build_search_next_step(response, query, { with_rerank, clarification_turns_used })
+
+	// Telemetry beacons (fire-and-forget). Spec § 5.1 + § 5.3.
+	if (with_rerank && next_step?.action === 'rank_digests_inline') {
+		fire_discovery_telemetry({
+			event: 'rerank_started',
+			query,
+			rerank_prompt_version: response?.rerank_prompt_version || null,
+		})
+	}
+	if (with_rerank && next_step?.action === 'clarify') {
+		fire_discovery_telemetry({
+			event:       'clarify_triggered',
+			query,
+			reason:      'match_notice',
+			turn_number: clarification_turns_used + 1,
+		})
+	}
+	if (with_rerank && clarification_turns_used > 0) {
+		// Re-searches after a clarify cycle. Fired whenever the agent comes back
+		// with a refined query.
+		fire_discovery_telemetry({
+			event:       'clarify_completed',
+			query,
+			turn_number: clarification_turns_used,
+		})
+	}
+
 	if (items.length === 0) {
 		if (args.flags.json) {
-			const data = { query, mode, results: [], count: 0 }
+			const data = { query, formulated_query: query, mode, results: [], count: 0 }
 			if (workspace_match !== undefined) data.workspace_match = workspace_match
 			if (server_match_notice) data.match_notice = server_match_notice
-			print_json({ data })
+			if (with_rerank) {
+				data.rerank_digests = response?.rerank_digests || []
+				data.rerank_system_prompt = response?.rerank_system_prompt || null
+				data.rerank_prompt_version = response?.rerank_prompt_version || null
+				data.rerank_response_schema = response?.rerank_response_schema || null
+			}
+			print_json(with_rerank ? { data, error: null, next_step } : { data })
 			return
 		}
 		if (mode === 'fuzzy_scoped' && workspace_match === null) {
@@ -167,10 +282,18 @@ const run_smart_search = (args, query, options) => catch_errors('Smart search fa
 				similarity: member.similarity != null ? member.similarity : null,
 			})),
 		}))
-		const data = { query, mode, results: mapped, count: mapped.length }
+		const data = { query, formulated_query: query, mode, results: mapped, count: mapped.length }
 		if (workspace_match !== undefined) data.workspace_match = workspace_match
 		if (match_notice) data.match_notice = match_notice
-		print_json({ data })
+		if (with_rerank) {
+			data.rerank_digests = response?.rerank_digests || []
+			data.rerank_system_prompt = response?.rerank_system_prompt || null
+			data.rerank_prompt_version = response?.rerank_prompt_version || null
+			data.rerank_response_schema = response?.rerank_response_schema || null
+		}
+		// Wrap in the universal envelope shape only when --with-rerank is set.
+		// Plain search keeps its existing { data: ... } shape for backward compat.
+		print_json(with_rerank ? { data, error: null, next_step } : { data })
 		return
 	}
 
@@ -183,6 +306,9 @@ const run_smart_search = (args, query, options) => catch_errors('Smart search fa
 		console.log(format_smart_result(item, i))
 		if (i < items.length - 1) console.log('')
 	})
+	if (with_rerank) {
+		console.log(`\n${dim('(--with-rerank set: rerank payload suppressed in human-readable mode. Use --json to consume.)')}\n`)
+	}
 	console.log(`\n${gray(`Showing ${items.length} result${items.length === 1 ? '' : 's'}. Install with: happyskills install <owner>/<name>`)}\n`)
 })
 
@@ -242,6 +368,7 @@ const run = (args) => catch_errors('Search failed', async () => {
 	const query = args._.join(' ') || null
 	const { mine, personal, workspace, tags, type } = args.flags
 	const is_exact = !!args.flags.exact
+	const with_rerank = !!args.flags['with-rerank']
 	// --smart / -S accepted for backward compat (now the default when a query is provided)
 	const use_smart = query && !is_exact
 	const has_scope_flag = mine || personal || workspace
@@ -258,6 +385,12 @@ const run = (args) => catch_errors('Search failed', async () => {
 		throw new UsageError(`--type must be one of: ${VALID_SKILL_TYPES.join(', ')}`)
 	}
 
+	// Spec 260521-01 v2 § 5.1 — --with-rerank requires semantic dispatch; --exact
+	// forces FTS-only mode where rerank is meaningless. Refuse the combination.
+	if (with_rerank && is_exact) {
+		throw new UsageError('--with-rerank cannot be combined with --exact. The rerank protocol applies only to semantic-mode dispatches.')
+	}
+
 	const scope = mine ? 'mine' : personal ? 'personal' : undefined
 
 	if (mine || personal) {
@@ -288,4 +421,4 @@ const run = (args) => catch_errors('Search failed', async () => {
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+module.exports = { run, build_search_next_step }

package/src/commands/search.test.js

@@ -0,0 +1,122 @@
+// Unit tests for the next_step envelope emission rules on
+// cli/src/commands/search.js. Spec 260521-01 v2 § 5.1.
+//
+// The orchestration around the actual HTTP call is covered by manual E2E
+// testing (spec § 7); here we lock down the pure decision logic.
+
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const { build_search_next_step } = require('./search')
+
+const make_response = (overrides = {}) => ({
+	mode:          'semantic',
+	data:          [],
+	match_notice:  null,
+	rerank_digests: null,
+	rerank_prompt_version: null,
+	...overrides,
+})
+
+describe('build_search_next_step', () => {
+	it('returns null 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)
+	})
+
+	it('returns null 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)
+	})
+
+	it('returns null 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)
+	})
+
+	it('emits rank_digests_inline when semantic mode + 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.match(r.instructions, /happyskills postlex/)
+		// Instructions should carry the budget forward to the next call.
+		assert.match(r.instructions, /--clarification-turns-used 0/)
+	})
+
+	it('propagates clarification_turns_used into the rank instructions', () => {
+		const r = build_search_next_step(make_response({
+			rerank_digests: [{ candidate_id: 1 }],
+		}), 'q', { with_rerank: true, clarification_turns_used: 1 })
+		assert.match(r.instructions, /--clarification-turns-used 1/)
+		assert.equal(r.context.clarification_turns_used, 1)
+	})
+
+	it('emits clarify when semantic + no digests + match_notice fires + 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.match(opts[opts.length - 1].label, /search anyway/i)
+		// 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', () => {
+		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.match(r.instructions, /budget.*spent/i)
+	})
+
+	it('returns null 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)
+	})
+
+	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)
+	})
+
+	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)
+		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')
+	})
+
+	it('the clarify 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.match(opts[3].label, /search anyway/i)
+		assert.equal(opts[3].refined_query_hint, null)
+	})
+})

package/src/constants.js

@@ -73,7 +73,8 @@ const COMMANDS = [
 	'disable',
 	'versions',
 	'changelog',
-	'agents'
+	'agents',
+	'postlex'
 ]
 
 module.exports = {

package/src/index.js

@@ -36,7 +36,7 @@ const parse_args = (argv) => {
 		if (arg.startsWith('--')) {
 			const key = arg.slice(2)
 			const next = argv[i + 1]
-			if (!next || next.startsWith('-')) {
+			if (!next || (next.startsWith('-') && next !== '-')) {
 				args.flags[key] = true
 			} else {
 				args.flags[key] = next
@@ -45,7 +45,7 @@ const parse_args = (argv) => {
 		} else if (arg.startsWith('-') && arg.length === 2) {
 			const key = arg.slice(1)
 			const next = argv[i + 1]
-			if (!next || next.startsWith('-')) {
+			if (!next || (next.startsWith('-') && next !== '-')) {
 				args.flags[key] = true
 			} else {
 				args.flags[key] = next
@@ -91,6 +91,7 @@ Commands:
   visibility <owner/skill> Check or set visibility (alias: vis)
   list                     List installed skills (alias: ls)
   search <query>           Search the registry (alias: s)
+  postlex                  Apply deterministic rerank finalization (agent-only; see happyskills-help skill)
   versions <owner/skill>   List all published versions of a skill
   changelog <owner/skill>  Print a skill's CHANGELOG.md
   check [owner/skill]      Check for available updates