happyskills 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -7,11 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.0.1] - 2026-06-01
+
+### Fixed
+
+- Fix the post-rerank clarification step in `postlex`: the `clarify_triggered` telemetry beacon and the text-mode clarification prompt checked for a `clarify` action and read `suggested_questions` at the wrong depth, but the command emits `clarify_query` with the questions nested under `next_step.context` — so neither fired. The `--json` envelope was already correct; this restores the CLI's own telemetry and human-readable clarification output.
+
 ## [1.0.0] - 2026-05-29
 
 ### Added
 
-- **Universal response envelope on every `--json` command** (spec 260525-cli-default-json). All structured output now emits a canonical six-key shape — `{ ok, data, error, next_step, warnings, meta }` — with `ok` derived from error presence, `data` always an object, and the process exit code mirrored into `meta.exit_code`. Agents can determine success/failure and the recovery path without parsing prose.
+- **Canonical six-key response envelope on every `--json` command** (spec 260525-cli-default-json). All structured output now emits a canonical six-key shape — `{ ok, data, error, next_step, warnings, meta }` — with `ok` derived from error presence, `data` always an object, and the process exit code mirrored into `meta.exit_code`. Agents can determine success/failure and the recovery path without parsing prose.
 - **`happyskills schema --json` command** — emits a machine-readable description of the entire CLI surface: every command, the closed `error_codes`, `next_step_actions`, and `next_step_kinds` enums. A generic agent can discover the full CLI contract in one call.
 - **Closed enums for the envelope** — `error.code` (state/auth/network/validation/etc.), `next_step.kind` (six kinds: recovery, clarification, decision, confirmation, continuation, routing), and `next_step.action` (~27 actions). Shipped as `cli/src/constants/{error_codes,next_step_actions}.js`, kept byte-identical with the API.
 - **Hand-rolled envelope validator** (`cli/src/schema/envelope_validator.js`) — enforces the closed schema, the `dependentRequired` clusters (code+message, kind+action+instructions), and the derived invariants. No new runtime dependency.
@@ -19,7 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Changed
 
-- **BREAKING: `--json` output format.** Every command's JSON output moved from the legacy `{ data }` / `{ error: { code, message, exit_code } }` shapes to the six-key envelope. `exit_code` now lives on `meta.exit_code`, not inside `error`. Consumers that parsed the old shapes must update — this is why the release is `1.0.0`.
+- **BREAKING: `--json` output format.** Every command's JSON output moved from the legacy `{ data }` / `{ error: { code, message, exit_code } }` shapes to the canonical six-key response envelope. `exit_code` now lives on `meta.exit_code`, not inside `error`. Consumers that parsed the old shapes must update — this is why the release is `1.0.0`.
 - **CLI consumes the new API envelope** while remaining backward-compatible with the current (pre-envelope) API. The `search`, `feedback`, and device-login clients detect the envelope and translate; against the old API they fall through to the legacy path, so the new CLI works against both.
 - **`error.code` is a closed enum end-to-end** — unknown codes from a newer API coerce to `UNKNOWN_CODE` with the original preserved under `error.details.original_code`.
 - **Per-command `next_step` recoveries** now use the closed action enum across `install`, `reconcile`, `release`, `search`, `postlex`, `validate`, `delete`, and `feedback` (e.g. `VERSION_NOT_FOUND` → `pick_version`, `LOCAL_EDITS_PRESENT` → `confirm_discard_or_snapshot_first`, `DRIFT_DETECTED` → `reconcile_first`).
@@ -181,14 +187,14 @@ This release combines two streams of work: **spec 260523-02 (Skill Update Determ
 ## [0.47.0] - 2026-05-21
 
 ### Added
-- Add `--with-rerank` flag to `happyskills search`. When set, the CLI passes `with_rerank_digests=true` to `POST /repos:search` (via `dispatch_search()`) and wraps the `--json` response in the universal envelope shape `{ data, error, next_step }`. The `data` payload gains four new fields alongside the existing `results`: `rerank_digests`, `rerank_system_prompt`, `rerank_prompt_version`, `rerank_response_schema`, plus `formulated_query`. `next_step.action` is one of `rank_digests_inline` (digests came back — agent ranks them and pipes to `postlex`), `clarify` (semantic match_notice fired and clarification budget remains — agent uses its native question mechanism with a calibrated narrowing question), or `present_to_user` (budget exhausted / non-semantic mode — render results). Silently ignored on non-semantic dispatches (slug-shape, scoped, exact). Combining `--with-rerank --exact` exits 2 (`USAGE_ERROR`). Intended for use inside an agentic session — see the `happyskills-help@0.3.0` skill's `references/discovery-protocol.md` for the envelope contract.
+- Add `--with-rerank` flag to `happyskills search`. When set, the CLI passes `with_rerank_digests=true` to `POST /repos:search` (via `dispatch_search()`) and wraps the `--json` response in the canonical six-key response envelope shape `{ data, error, next_step }`. The `data` payload gains four new fields alongside the existing `results`: `rerank_digests`, `rerank_system_prompt`, `rerank_prompt_version`, `rerank_response_schema`, plus `formulated_query`. `next_step.action` is one of `rank_digests_inline` (digests came back — agent ranks them and pipes to `postlex`), `clarify` (semantic match_notice fired and clarification budget remains — agent uses its native question mechanism with a calibrated narrowing question), or `present_to_user` (budget exhausted / non-semantic mode — render results). Silently ignored on non-semantic dispatches (slug-shape, scoped, exact). Combining `--with-rerank --exact` exits 2 (`USAGE_ERROR`). Intended for use inside an agentic session — see the `happyskills-help@0.3.0` skill's `references/discovery-protocol.md` for the envelope contract.
 - Add `--clarification-turns-used <N>` companion flag on `search`. Carries the clarification budget (0–2, default 0) across re-searches in the discovery protocol's clarification flow. The CLI clamps to the hard cap of 2 and emits `present_to_user` (instead of `clarify`) once the budget is spent.
 - Add new `happyskills postlex` subcommand — deterministic post-lex finalization for the discovery protocol. Takes the LLM's `ranking[]` JSON plus the original `data[]` array (from stdin via `--ranking -`, or from separate `--ranking <file>` + `--data <file>` paths), applies the canonical 30-line slug-overlap promotion algorithm, and emits a `next_step` envelope (`present_to_user` on success, `clarify` if the post-rerank top results are still weak and budget remains, `retry_rank` with an `input_template` when the ranking fails schema validation). Stateless — the agent carries all cross-call state via `--clarification-turns-used` and `next_step.context`. Human-readable output renders only the LLM-ranked subset (the unranked tail is not shown — the LLM chose not to rank those rows). Refuses to crash on out-of-range `candidate_id` values: invalid entries are dropped with a stderr warning; if every entry drops out, exit 1.
 - Add `cli/src/utils/slug_tokens.js` — STOP_TOKENS + `slug_tokens()` + `slug_token_set()` + `compute_lex_tier()`. Byte-identical mirror of `api/app/utils/slug_tokens.js`. The companion test (`slug_tokens.test.js`) cross-imports the API canonical version and asserts STOP_TOKENS set-equality in both directions — fails CI loud if either side drifts. This is the load-bearing invariant from spec 260521-01 v2 § 6: if the CLI's view of which candidate is "exact" disagrees with the API's slug-boost behavior, the post-lex stage promotes the wrong candidate (or none).
 - Add `cli/src/api/telemetry.js` — fire-and-forget client for `POST /telemetry/discovery`. 2-second `AbortController` timeout; all errors swallowed; never affects exit codes. Called from `search` (events `rerank_started` when emitting `rank_digests_inline`, `clarify_triggered` when emitting `clarify`, `clarify_completed` when re-running after a clarify cycle) and from `postlex` (event `rerank_completed` after the algorithm runs, plus `clarify_triggered` when emitting a post-rerank clarify). Server-side aggregation in CloudWatch Insights drives the two key signals: postlex fire rate (0.5%–5% target) and protocol completion rate (≥85% target — `count(rerank_completed)/count(rerank_started)`).
 
 ### Changed
-- `search --json` output is wrapped in the universal envelope `{ data, error, next_step }` when (and only when) `--with-rerank` is set. Plain `search --json` (without the flag) keeps its existing `{ data: { … } }` shape for backward compatibility — no consumer of the existing JSON contract sees a change.
+- `search --json` output is wrapped in the canonical six-key response envelope `{ data, error, next_step }` when (and only when) `--with-rerank` is set. Plain `search --json` (without the flag) keeps its existing `{ data: { … } }` shape for backward compatibility — no consumer of the existing JSON contract sees a change.
 - Argument parser (`parse_args` in `cli/src/index.js`) now treats a literal `-` as a flag value instead of as the prefix of another flag. This is the standard Unix stdin sentinel and lets `happyskills postlex --ranking -` parse correctly. Conservative change: `next.startsWith('-') && next !== '-'` is the new gate, so any flag whose value would previously have been swallowed and replaced with `true` because the next arg happened to be `-` now correctly receives `'-'`. No existing command relied on the previous behavior.
 
 ## [0.46.1] - 2026-05-20

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "1.0.0",
+	"version": "1.0.1",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",

package/src/api/translate.js

@@ -1,6 +1,6 @@
 'use strict'
 // Post-Session-3 translator: near-identity. The public API now emits the
-// canonical six-key envelope natively (spec 260525-cli-default-json § 11),
+// canonical six-key response envelope natively (spec 260525-cli-default-json § 11),
 // so this module only stamps the CLI's local `meta.cli_version` on top of
 // the response — meta.api_version is preserved verbatim. Forward-compat
 // for unknown error codes still routes through UNKNOWN_CODE per § 5.2.

package/src/commands/feedback.js

@@ -3,7 +3,7 @@
 // Surfaces:
 //   happyskills feedback <category> [body] [--subject "..."] [--attach a,b,c] [--json]
 //
-// --json mode emits the API's response wrapped in the universal CLI envelope:
+// --json mode emits the API's response wrapped in the canonical six-key response envelope:
 //   { data: { feedback, next_step, attachments? }, error: null }
 // The `next_step` envelope is what the `happyskills-help` skill reads to
 // route the post-creation conversation (offer attachment, etc.) — see spec
@@ -240,7 +240,7 @@ const run = (args) => catch_errors('Feedback command failed', async () => {
 	}
 
 	if (json_mode) {
-		// Universal CLI envelope shape. The skill's envelope-reader (per spec
+		// Canonical six-key response envelope shape. The skill's envelope-reader (per spec
 		// § 11) consumes `next_step` at the response root.
 		const data = { feedback, attachments }
 		print_json({ data, error: null, next_step })

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')
@@ -218,8 +218,30 @@ const determine_next_step = (final_ordering, query, clarification_turns_used) =>
 	}
 }
 
+// ─── 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. Returns the canonical six-key envelope (spec § 4) so postlex
+// 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')
@@ -450,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,
@@ -487,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).')}`)
 	}
@@ -503,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,
@@ -224,6 +226,52 @@ 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,

package/src/commands/search.js

@@ -305,7 +305,7 @@ const run_smart_search = (args, query, options) => catch_errors('Smart search fa
 			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.
+		// Wrap in the canonical six-key response 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

package/src/commands/search.test.js

@@ -91,7 +91,7 @@ describe('build_search_next_step — envelope shape', () => {
 		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_envelope_next_step(r, NEXT_STEP_ACTIONS.CLARIFY_QUERY, 'clarify')
+		assert_envelope_next_step(r, NEXT_STEP_ACTIONS.CLARIFY_QUERY, 'clarify_query')
 		// 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))

package/src/constants/error_codes.js

@@ -1,5 +1,5 @@
 'use strict'
-// Closed enum of error codes emitted by the CLI envelope. Mirrors spec
+// Closed enum of error codes emitted by the canonical six-key response 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).

package/src/integration/api_envelope.test.js

@@ -1,7 +1,7 @@
 'use strict'
 /**
  * End-to-end integration tests: CLI ↔ stubbed API speaking the new
- * canonical six-key envelope (spec 260525-cli-default-json § 4).
+ * canonical six-key response envelope (spec 260525-cli-default-json § 4).
  *
  * We spin up a tiny `http.createServer` per test that emits the EXACT
  * envelope the production API now returns (post-Session 3), point the
@@ -33,7 +33,7 @@ const NODE = process.execPath
 
 // Minimal stub-server harness. Each test installs a route table that maps
 // `${METHOD} ${PATH}` → handler({ url, body }) returning { status, body }.
-// The body is always JSON-encoded with the new six-key envelope shape.
+// The body is always JSON-encoded with the new canonical six-key response envelope shape.
 //
 // IMPORTANT: every response carries `Connection: close`. Without this,
 // undici's connection pool keeps the socket warm and prevents the CLI

package/src/integration/reconcile.test.js

@@ -1,7 +1,7 @@
 'use strict'
 /**
  * Integration tests for `happyskills reconcile` — § 8.4 + envelope refactor
- * (spec 260525-cli-default-json). Asserts on the SIX-KEY envelope shape:
+ * (spec 260525-cli-default-json). Asserts on the canonical six-key response 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.

package/src/integration/release.test.js

@@ -1,7 +1,7 @@
 'use strict'
 /**
  * Integration tests for `happyskills release` — § 8.2 + envelope refactor
- * (spec 260525-cli-default-json). Asserts on the six-key envelope shape and
+ * (spec 260525-cli-default-json). Asserts on the canonical six-key response envelope shape and
  * the closed `next_step.action` enum.
  *
  * Focus: the failure-mode envelopes (drift, missing_version, missing_changelog

package/src/integration/schema.test.js

@@ -6,7 +6,7 @@
  * command, every error code, and every next_step.action in one call.
  *
  * Coverage:
- *   - Envelope conforms to the closed schema (validated via parse_envelope).
+ *   - The canonical six-key response envelope conforms to the closed schema (validated via parse_envelope).
  *   - data.envelope_schema_version + data.envelope_schema_uri present.
  *   - data.commands carries one entry per known CLI command, each with
  *     name, audience, input, output, errors[].

package/src/ui/envelope.js

@@ -1,7 +1,7 @@
 'use strict'
 // The single chokepoint for CLI JSON output. Spec 260525-cli-default-json
 // § 4 + § 8. Every command's --json path goes through emit_envelope; the
-// helper builds the canonical six-key envelope, derives `ok`, mirrors the
+// helper builds the canonical six-key response envelope, derives `ok`, mirrors the
 // exit code into `meta`, validates against the closed schema (dev
 // assertion only — never throws in prod), serialises with 2-space indent,
 // writes to stdout, and (when called via emit_and_exit) calls process.exit.

package/src/ui/output.js

@@ -110,14 +110,14 @@ const summarize_warnings = (warnings, skill_name) => {
 
 // print_json now routes through the central envelope chokepoint when given
 // an envelope-shaped input ({ data }, { error }, { next_step }, or a full
-// six-key envelope). This retrofits every legacy `print_json({ data: ... })`
+// canonical six-key response envelope). This retrofits every legacy `print_json({ data: ... })`
 // call site to emit the new schema without changing the call. Raw inputs
 // (e.g. a bare array) fall through to the legacy JSON.stringify path so
 // scripts/validators that print free-form JSON still work.
 //
 // Audit follow-up #6 — dev-mode strict assertion. When
 // HAPPYSKILLS_ENVELOPE_STRICT=1 (or NODE_ENV=test), any top-level key
-// outside the six-key envelope is written to stderr as a warning. This
+// outside the canonical six-key response envelope is written to stderr as a warning. This
 // catches the `uninstall.js:79` / `install.js:244` class bug — callers
 // passing a sibling field (`errors:` plural, `attachments:`, etc.) that
 // the retrofit would silently drop. Production stays quiet.