akm-cli 0.9.2-alpha.1 → 0.9.2-alpha.2

package/CHANGELOG.md

@@ -6,6 +6,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.2-alpha.2] - 2026-08-25
+
+- TODO
+
 ## [0.9.2-alpha.1] - 2026-08-24
 
 ### Breaking changes & migration
@@ -1213,34 +1217,17 @@ See `docs/migration/v0.8-to-v0.9.md` and
   and a real domain asset always outranks the facts. That invariant is pinned
   by `tests/search-convention-fact-demotion.test.ts`, which becomes the
   regression guard if a demotion contributor is ever revisited.
-- **Config-gated indexing of the self-situating body opening —
-  `index.indexBodyOpening` (default `false`).** Body prose is not indexed
-  (the FTS `content` column carries only TOC headings and parameters), which
-  is why the stash conventions route orientation into
-  `description:`/`when_to_use:`. With the new flag enabled, the metadata pass
-  captures the first prose paragraph of each markdown asset body — skipping
-  headings (ATX and setext), fenced code blocks, thematic breaks, and a
-  leading nested frontmatter block (only when its content is actually
-  frontmatter-shaped: prose wrapped in decorative `---` lines is captured,
-  not discarded); capped at 280 chars with word-boundary truncation and a
-  trailing ellipsis — into `entry.bodyOpening`, which folds into the
-  lowest-weight `content` FTS column (bm25 weight 1.0, so a name match always
-  outranks a body-opening-only match) and into the search/embedding text.
-  Secret and env files are never read for it, and session-kind memories
-  (`akm_memory_kind` in outer or nested inner frontmatter) are excluded —
-  their bodies are raw transcripts. Both indexing walks and write-path
-  indexing honor the flag (the metadata pass reads the user config directly).
-  With the flag absent or `false`, entries and search fields stay
-  byte-identical to before. **Costs of toggling (either direction):** indexed
-  text changes, so collapse-detector canary recall baselines shift — re-mint
-  via `akm improve canary --refresh` — and embeddings are NOT regenerated for
-  entries that already have one, while incremental runs re-extract only
-  changed files. Run `akm index --full` after toggling: it re-extracts every
-  entry and wipes embeddings so they rebuild from the new text; until then
-  `akm index` warns that the flag differs from the state the index was built
-  with. The conventions' `description:`/`when_to_use:` orientation routing
-  remains primary — this flag makes body openings additionally pay retrieval
-  rent, it does not replace structured metadata. See `docs/configuration.md`.
+- **One progressive lexical retrieval path and searchable Markdown prose.**
+  FTS now tokenizes Unicode letters/numbers, deduplicates and caps the query,
+  then runs strict AND, prefix-AND, and a single OR/prefix-OR recovery only
+  after both conjunctive forms miss. Every stage keeps the existing BM25 field
+  weights and downstream ranker; callers do not maintain stopword lists or
+  parallel result collections. AKM-native Markdown contributes a normalized,
+  16,384-character body projection through the existing lowest-weight
+  `content` field. Frontmatter, comments, fenced code, and link destinations
+  are removed; secret/env values and raw session/checkpoint bodies never enter
+  the projection. Structured fields remain first in the bounded embedding
+  input, so exact names and metadata continue to dominate body-only matches.
 - **`akm mv <ref> <new-name>` — rename with inbound-xref rewrite and
   utility-history preservation (Experimental).** The stash conventions'
   forced-rename procedure ("grep and fix inbound xrefs in the same pass") was

package/dist/assets/stash-skeleton/facts/conventions/backlinks.md

@@ -73,10 +73,9 @@ xrefs:
 ## Self-situating headers and canonical naming
 
 Put the one-line orientation in `description:` and the trigger conditions in
-`when_to_use:` — those are indexed fields; body prose is not indexed by
-default (only headings reach the index; the opt-in `index.indexBodyOpening`
-flag adds just the first body paragraph, at the lowest weight —
-`description:`/`when_to_use:` remain the primary orientation channel). Then
+`when_to_use:` — those remain the higher-weight indexed fields. Bounded body
+prose is indexed in the lowest-weight `content` field, so
+`description:`/`when_to_use:` remain the primary orientation channel. Then
 open the body with a plain title plus a one-line
 orientation naming what it is, its scope/domain, and its key entities in
 canonical spelling (`Postgres`, `OAuth`, `TLS`, `Acme`) — the entity/relation

package/dist/assets/stash-skeleton/facts/conventions/organization.md

@@ -86,9 +86,7 @@ cross-project reuse.
   (`acme` vs `acme-corp`) so the prefix does not fragment. Keep the domain
   vocabulary in `facts/conventions/domains`.
 - **Off-axis facets go in `tags:`, not a bare field.** The indexed FTS fields are
-  name, description, tags, hints, and content (headings only — body prose is
-  not indexed by default; the opt-in `index.indexBodyOpening` flag adds just
-  the first body paragraph, at the lowest weight) — there is **no `project`
+  name, description, tags, hints, and bounded low-weight body content — there is **no `project`
   field**, so `project: projectA` in
   frontmatter is invisible to search. Put the off-axis facet in `tags` instead
   (a project-scoped memory adds `tags: [auth]`; a domain-scoped asset genuinely

package/dist/commands/improve/collapse-detector.js

@@ -163,10 +163,9 @@ export function refreshCanarySet(stateDb, indexDb, cfg) {
  * Name-free content fingerprint text for entropy metrics. The indexed
  * search_text EMBEDS the (unique) entry name, which would pin the
  * distinct-content ratio at 1.0 forever; convergence shows up in the
- * description/tags/heading fields, so those are what get hashed. (The raw body
- * is not in the index at all — search_text covers metadata + TOC headings —
- * so v1 entropy is measured over the searchable surface, which is also what
- * generic merged assets converge on.)
+ * description/tags/heading fields, so those are what get hashed. Bounded body
+ * content is searchable but deliberately excluded from this fingerprint: the
+ * detector measures the structured surface generic merged assets converge on.
  */
 function contentFingerprint(entry) {
     const parts = [entry.description ?? "", (entry.tags ?? []).join(" "), (entry.toc ?? []).map((h) => h.text).join(" ")];

package/dist/commands/improve/extract-prompt.js

@@ -15,6 +15,7 @@
  * the model emits get dropped before we parse.
  */
 import promptTemplate from "../../assets/prompts/extract-session.md" with { type: "text" };
+import { escapeJsonStringControls, stripCodeFences, stripThinkBlocks } from "../../core/parse.js";
 const EXTRACT_CANDIDATE_NAME_PATTERN = "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:/[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)?$";
 const EXTRACT_CANDIDATE_NAME_RE = new RegExp(EXTRACT_CANDIDATE_NAME_PATTERN);
 /**
@@ -163,6 +164,57 @@ export function buildExtractPrompt(input) {
         .replace("{{STANDARDS}}", standards)
         .replace("{{TRANSCRIPT}}", `${TRANSCRIPT_FENCE_BEGIN}\n${formatTranscript(input.events)}\n${TRANSCRIPT_FENCE_END}`);
 }
+function failedExtractPayload(code, message) {
+    return { candidates: [], rationale_if_empty: message, parseFailure: { code, message } };
+}
+function parseFirstJsonObject(stdout) {
+    const text = escapeJsonStringControls(stripCodeFences(stripThinkBlocks(stdout)));
+    try {
+        return { objectFound: text.startsWith("{"), value: JSON.parse(text) };
+    }
+    catch {
+        // Continue with the first object embedded in prose. Once an opening brace
+        // is found, never descend into a nested object if that outer object is
+        // malformed or truncated: doing so can turn a broken candidate into a
+        // superficially valid top-level payload.
+    }
+    const start = text.indexOf("{");
+    if (start < 0)
+        return { objectFound: false };
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let index = start; index < text.length; index++) {
+        const char = text[index];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (char === "\\")
+                escaped = true;
+            else if (char === '"')
+                inString = false;
+            continue;
+        }
+        if (char === '"') {
+            inString = true;
+            continue;
+        }
+        if (char === "{")
+            depth += 1;
+        else if (char === "}") {
+            depth -= 1;
+            if (depth !== 0)
+                continue;
+            try {
+                return { objectFound: true, value: JSON.parse(text.slice(start, index + 1)) };
+            }
+            catch {
+                return { objectFound: true };
+            }
+        }
+    }
+    return { objectFound: true };
+}
 /**
  * Parse the LLM's JSON response into a structured {@link ExtractPayload}.
  * Defensive — drops candidates that violate the shape rather than failing
@@ -170,32 +222,22 @@ export function buildExtractPrompt(input) {
  */
 export function parseExtractPayload(stdout) {
     if (!stdout || stdout.trim().length === 0) {
-        return { candidates: [], rationale_if_empty: "LLM returned empty response" };
+        return failedExtractPayload("empty_response", "LLM returned an empty response");
     }
-    let parsed;
-    try {
-        parsed = JSON.parse(stdout);
+    const parsed = parseFirstJsonObject(stdout);
+    if (parsed.value === undefined) {
+        return parsed.objectFound
+            ? failedExtractPayload("invalid_json_object", "JSON object was found but could not be parsed")
+            : failedExtractPayload("no_json_object", "LLM response: no JSON object found");
     }
-    catch {
-        // Tolerate prose preamble/postamble by extracting the first balanced
-        // top-level JSON object.
-        const start = stdout.indexOf("{");
-        const end = stdout.lastIndexOf("}");
-        if (start === -1 || end <= start) {
-            return { candidates: [], rationale_if_empty: `LLM response was not parseable JSON` };
-        }
-        try {
-            parsed = JSON.parse(stdout.slice(start, end + 1));
-        }
-        catch {
-            return { candidates: [], rationale_if_empty: `LLM response was not parseable JSON` };
-        }
+    if (!parsed.value || typeof parsed.value !== "object" || Array.isArray(parsed.value)) {
+        return failedExtractPayload("invalid_payload", "LLM response JSON was not an object");
     }
-    if (!parsed || typeof parsed !== "object") {
-        return { candidates: [], rationale_if_empty: "LLM response was not an object" };
+    const obj = parsed.value;
+    if (!Array.isArray(obj.candidates)) {
+        return failedExtractPayload("invalid_payload", "LLM response JSON did not contain a candidates array");
     }
-    const obj = parsed;
-    const rawCandidates = Array.isArray(obj.candidates) ? obj.candidates : [];
+    const rawCandidates = obj.candidates;
     const candidates = [];
     for (const raw of rawCandidates) {
         if (!raw || typeof raw !== "object")

package/dist/commands/improve/extract.js

@@ -32,12 +32,14 @@ import { ConfigError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync, } from "../../core/file-lock.js";
 import { tryAcquireMaintenanceBarrier } from "../../core/maintenance-barrier.js";
+import { redactErrorBody } from "../../core/redaction.js";
 import { resolveStashStandards } from "../../core/standards/resolve-stash-standards.js";
 import { resolveTypeConventions, typeConventionRef } from "../../core/standards/resolve-type-conventions.js";
 import { getStateDbPath, openStateDatabase } from "../../core/state-db.js";
+import { runStructured } from "../../core/structured.js";
 import { repairTruncatedDescription } from "../../core/text-truncation.js";
 import { DURATION_UNITS, parseDuration } from "../../core/time.js";
-import { warn } from "../../core/warn.js";
+import { warn, warnVerbose } from "../../core/warn.js";
 import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
 import { disposeLoweredExecutionDispatchLease, } from "../../integrations/agent/execution-lowering.js";
 import { getAvailableHarnesses } from "../../integrations/session-logs/index.js";
@@ -48,7 +50,7 @@ import { getExtractedSessionsMap, getLastExtractRunAt, shouldSkipAlreadyExtracte
 import { openSqliteReadSnapshot } from "../../storage/sqlite-read-snapshot.js";
 import { isProposalSkipped } from "../proposal/repository.js";
 import { resolveImproveLlmExecution } from "./execution.js";
-import { buildExtractPrompt, EXTRACT_JSON_SCHEMA, parseExtractPayload } from "./extract-prompt.js";
+import { buildExtractPrompt, EXTRACT_JSON_SCHEMA, parseExtractPayload, } from "./extract-prompt.js";
 import { resolveImproveStrategy, resolveProcessEnabled } from "./improve-strategies.js";
 import { emitProposal } from "./proposal-envelope.js";
 import { createRunContext, resolveRunStashDir } from "./run-context.js";
@@ -507,45 +509,101 @@ function planExtractSessions(args) {
     }
     return { plans, deferredCandidates: [] };
 }
-/**
- * The bounded per-session extraction LLM call. Routes the already-resolved
- * symbolic runner through `callStructured` under the `session_extraction`
- * gate. Invalid configuration escapes before session/proposal state is
- * persisted. Returns the seam result plus the `llmRaw`
- * side-channel value that distinguishes fallback-took-over from a
- * genuinely-empty response.
- */
+const EXTRACT_LLM_UNAVAILABLE = Symbol("extract-llm-unavailable");
 async function runSessionExtractionLlmCall(args) {
     const { config, llmRunner, lease, chat, prompt, timeoutMs, signal, onNotices } = args;
-    let llmRaw = "";
-    const llmResult = await callStructured({
-        feature: "session_extraction",
-        akmConfig: config,
-        runner: llmRunner,
-        lease,
-        messages: [{ role: "user", content: prompt }],
-        request: {
-            timeoutMs,
-            responseSchema: EXTRACT_JSON_SCHEMA,
-            ...(signal ? { signal } : {}),
-            ...(chat ? { chat } : {}),
-        },
-        onNotices,
-        parse: (raw) => {
-            llmRaw = raw ?? "";
-            return llmRaw;
-        },
-        // A transport throw takes the "" fallback with llmRaw left unset —
-        // the same skipped path the gated-fn throw produced before.
-        onError: () => "",
-        fallback: "",
-    });
-    return { llmResult, llmRaw };
+    try {
+        const result = await runStructured({
+            dispatch: async (feedback) => {
+                const content = feedback ? `${prompt}\n\n## Corrective output instruction\n\n${feedback}` : prompt;
+                const dispatched = await callStructured({
+                    feature: "session_extraction",
+                    akmConfig: config,
+                    runner: llmRunner,
+                    lease,
+                    messages: [{ role: "user", content }],
+                    request: {
+                        timeoutMs,
+                        responseSchema: EXTRACT_JSON_SCHEMA,
+                        ...(signal ? { signal } : {}),
+                        ...(chat ? { chat } : {}),
+                    },
+                    onNotices,
+                    parse: (raw) => ({ kind: "response", raw: raw ?? "" }),
+                    onError: () => ({ kind: "unavailable" }),
+                    fallback: { kind: "unavailable" },
+                });
+                if (dispatched.kind === "unavailable")
+                    throw EXTRACT_LLM_UNAVAILABLE;
+                return dispatched.raw;
+            },
+            parse: (raw) => {
+                const payload = parseExtractPayload(raw);
+                return payload.parseFailure ? undefined : payload;
+            },
+            validate: (payload) => ({ ok: true, value: payload }),
+            maxAttempts: llmRunner.connection.supportsJsonSchema === true ? 1 : 2,
+            buildFeedback: () => "Your previous response did not contain a valid extraction payload. Respond with ONLY a JSON object matching the requested schema, with a candidates array and no prose or code fences.",
+        });
+        if (result.ok)
+            return { kind: "success", payload: result.value, attempts: result.attempts };
+        const payload = parseExtractPayload(result.raw);
+        return {
+            kind: "malformed",
+            raw: result.raw,
+            attempts: result.attempts,
+            failure: payload.parseFailure ??
+                { code: "invalid_payload", message: result.errors.join("; ") },
+        };
+    }
+    catch (err) {
+        if (err === EXTRACT_LLM_UNAVAILABLE)
+            return { kind: "unavailable" };
+        throw err;
+    }
 }
 function extractNoticeFields(getNotices) {
     const notices = getNotices();
     return notices.length > 0 ? { notices } : {};
 }
+function extractPreFilterStats(filtered) {
+    return {
+        inputCount: filtered.stats.inputCount,
+        outputCount: filtered.stats.outputCount,
+        truncatedCount: filtered.stats.truncatedCount,
+    };
+}
+function malformedExtractionResult(args) {
+    const { extraction, sessionRef, harness, preFilter, contentHash, notices } = args;
+    const diagnostic = `malformed_model_output: ${extraction.failure.message}; attempts=${extraction.attempts}; responseLength=${extraction.raw.length}; responseSha256=${sha256Hex(extraction.raw)}`;
+    warnVerbose(`[extract] malformed model output for session ${sessionRef.sessionId}: ${redactErrorBody(extraction.raw)}`);
+    return {
+        sessionId: sessionRef.sessionId,
+        harness,
+        candidateCount: 0,
+        proposalIds: [],
+        preFilter,
+        warnings: [diagnostic],
+        skipped: true,
+        skipReason: "malformed_model_output",
+        contentHash,
+        ...notices,
+    };
+}
+function unavailableExtractionResult(args) {
+    return {
+        sessionId: args.sessionRef.sessionId,
+        harness: args.harness,
+        candidateCount: 0,
+        proposalIds: [],
+        preFilter: args.preFilter,
+        warnings: ["session_extraction feature returned empty (disabled / timeout / error)"],
+        skipped: true,
+        skipReason: "llm_unavailable",
+        contentHash: args.contentHash,
+        ...args.notices,
+    };
+}
 async function processSession(runCtx, session) {
     const { harness, stashDir, config, llmRunner, lease, onNotices, getNotices, chat, ctx, eventsCtx, sourceRun, dryRun, timeoutMs, sessionIndexing, signal, standardsContext, } = runCtx;
     const { sessionRef, gate } = session;
@@ -589,7 +647,7 @@ async function processSession(runCtx, session) {
         }
         return {};
     };
-    const { llmResult, llmRaw } = await runSessionExtractionLlmCall({
+    const extraction = await runSessionExtractionLlmCall({
         config,
         llmRunner,
         lease,
@@ -599,26 +657,27 @@ async function processSession(runCtx, session) {
         signal,
         onNotices,
     });
-    if (llmResult === "" && !llmRaw) {
+    if (extraction.kind === "unavailable") {
         // The seam took the fallback path (disabled / timeout / error). Return skipped.
-        return {
-            sessionId: sessionRef.sessionId,
+        return unavailableExtractionResult({
+            sessionRef,
             harness: harness.name,
-            candidateCount: 0,
-            proposalIds: [],
-            preFilter: {
-                inputCount: filtered.stats.inputCount,
-                outputCount: filtered.stats.outputCount,
-                truncatedCount: filtered.stats.truncatedCount,
-            },
-            warnings: ["session_extraction feature returned empty (disabled / timeout / error)"],
-            skipped: true,
-            skipReason: "llm_unavailable",
+            preFilter: extractPreFilterStats(filtered),
             contentHash,
-            ...extractNoticeFields(getNotices),
-        };
+            notices: extractNoticeFields(getNotices),
+        });
+    }
+    if (extraction.kind === "malformed") {
+        return malformedExtractionResult({
+            extraction,
+            sessionRef,
+            harness: harness.name,
+            preFilter: extractPreFilterStats(filtered),
+            contentHash,
+            notices: extractNoticeFields(getNotices),
+        });
     }
-    const payload = parseExtractPayload(llmRaw);
+    const { payload } = extraction;
     const proposalIds = [];
     // Provenance refs are added only after the cited session asset exists.
     const sessionAsset = await maybeWriteSessionAsset();
@@ -632,6 +691,7 @@ async function processSession(runCtx, session) {
                 harness: harness.name,
                 sourceRun,
                 rationale: payload.rationale_if_empty,
+                repairAttempts: extraction.attempts - 1,
                 preFilterInput: filtered.stats.inputCount,
                 preFilterOutput: filtered.stats.outputCount,
             },
@@ -705,6 +765,7 @@ async function processSession(runCtx, session) {
             proposalCount: proposalIds.length,
             preFilterInput: filtered.stats.inputCount,
             preFilterOutput: filtered.stats.outputCount,
+            repairAttempts: extraction.attempts - 1,
         },
     }, eventsCtx);
     return {
@@ -733,7 +794,9 @@ function recordExtractSessionOutcome(args) {
         return;
     try {
         const outcome = result.skipped
-            ? result.skipReason === "read_failed" || result.skipReason === "exception"
+            ? result.skipReason === "read_failed" ||
+                result.skipReason === "exception" ||
+                result.skipReason === "malformed_model_output"
                 ? "failed"
                 : "skipped"
             : result.candidateCount === 0
@@ -749,7 +812,9 @@ function recordExtractSessionOutcome(args) {
             proposalCount: result.proposalIds.length,
             rationale: result.rationaleIfEmpty ?? null,
             sourceRun,
-            contentHash: result.skipReason === "llm_unavailable" || result.skipReason === "triaged_out"
+            contentHash: result.skipReason === "llm_unavailable" ||
+                result.skipReason === "triaged_out" ||
+                result.skipReason === "malformed_model_output"
                 ? null
                 : (result.contentHash ?? null),
             metadata: {
@@ -908,6 +973,10 @@ async function runExtractSessionLoop(args) {
                 sessionRef: summary,
                 gate: executionGate,
             });
+            if (result.skipReason === "malformed_model_output") {
+                for (const warning of result.warnings)
+                    topLevelWarnings.push(`session ${summary.sessionId}: ${warning}`);
+            }
             accountExtractSessionResult(result, triage.enabled, output);
             recordExtractSessionOutcome({
                 stateDb,

package/dist/commands/read/curate.js

@@ -307,16 +307,12 @@ export function deriveCurateFallbackQueries(query) {
     return tokens;
 }
 export function mergeCurateSearchResponses(base, extras) {
-    // The base (full-query) ranking is the relevance signal — keyword fallback
-    // searches exist only to ADD recall when that ranking is thin, never to
-    // re-rank it. So we PRESERVE base order and APPEND fallback-only hits below
-    // it. A single-token fallback match on an exact title/path normalizes to a
-    // high FTS score, but those scores are not comparable to the full-query
-    // (hybrid) scores; re-sorting the union by raw score (the prior behaviour)
-    // let that keyword junk leapfrog the contextually-relevant full-query hits.
-    // Dup refs (present in both base and a fallback) keep their base POSITION but
-    // take the MAX score, since matching both the full query and a key term is a
-    // stronger relevance signal for the downstream score floor.
+    // The base (full-query) ranking is authoritative by default; keyword
+    // fallbacks add recall without comparing their raw scores to the full-query
+    // score scale. Base order is preserved and fallback-only hits append below,
+    // except for the narrow weak-provenance promotion documented below. Duplicate
+    // refs keep their base position but take the maximum score for the downstream
+    // relevance floor.
     const bestExtraStashScore = new Map();
     for (const result of extras) {
         for (const hit of result.hits.filter((entry) => entry.type !== "registry")) {
@@ -342,22 +338,39 @@ export function mergeCurateSearchResponses(base, extras) {
                 extraOnly.set(hit.ref, hit);
         }
     }
-    // Fallback-only hits must rank BELOW every full-query hit through the rest of
-    // the pipeline. The downstream selector (`selectCuratedStashHits`) RE-SORTS by
-    // score and derives its relevance floor from the top score, so preserving
-    // order here is not enough — a single-token FTS match (normalized ~0.9) would
-    // otherwise become the leader and evict the contextual full-query memories.
-    // We therefore restamp fallback-only scores into a band strictly below the
-    // minimum base score (keeping their own relative order). When there are no
-    // base hits, fallback IS the result, so scores are kept as-is.
+    // Fallback-only hits ordinarily stay below every full-query hit through the
+    // downstream selector, which re-sorts by score and derives its relevance
+    // floor from the leader. Restamping them below the minimum base score keeps a
+    // single-token score from leapfrogging contextual results. The one exception
+    // is a strong name match repairing a lexically weak base, selected below.
     const sortedExtra = [...extraOnly.values()].sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+    const lexicalAttribution = (hit) => getSearchHitAttribution(hit)?.lexical;
+    // The full-query base remains authoritative unless its lexical provenance is
+    // itself weak: relaxed recovery, or no hit whose name covers the query. In
+    // that case one fallback discovery with strong name coverage may lead. This
+    // preserves contextual base ranking while allowing measured recall to repair
+    // a thin match without comparing unrelated raw FTS score scales.
+    const weakLexicalBase = baseStash.length > 0 &&
+        baseStash.every((hit) => {
+            const lexical = lexicalAttribution(hit);
+            return lexical !== undefined && (lexical.execution === "relaxed" || lexical.nameMatchTier < 2);
+        });
+    const promotedExtraIndex = weakLexicalBase
+        ? sortedExtra.findIndex((hit) => (lexicalAttribution(hit)?.nameMatchTier ?? 0) >= 2)
+        : -1;
+    const promotedExtra = promotedExtraIndex >= 0 ? sortedExtra[promotedExtraIndex] : undefined;
+    const remainingExtra = promotedExtraIndex >= 0 ? sortedExtra.filter((_, index) => index !== promotedExtraIndex) : sortedExtra;
     const minBaseScore = baseStash.length
         ? Math.min(...baseStash.map((hit) => hit.score ?? 0))
         : Number.POSITIVE_INFINITY;
     const cappedExtra = baseStash.length
-        ? sortedExtra.map((hit, i) => ({ ...hit, score: minBaseScore - 1e-6 * (i + 1) }))
-        : sortedExtra;
-    const mergedHits = [...baseStash, ...cappedExtra];
+        ? remainingExtra.map((hit, i) => ({ ...hit, score: minBaseScore - 1e-6 * (i + 1) }))
+        : remainingExtra;
+    const mergedHits = [
+        ...(promotedExtra ? [{ ...promotedExtra, score: minBaseScore }] : []),
+        ...baseStash,
+        ...cappedExtra,
+    ];
     // Registry hits are supplemental fill — same rule: base first (max score on
     // dups), then fallback-only registry hits appended by score.
     const bestExtraRegScore = new Map();
@@ -585,8 +598,16 @@ function collapseCurateFamilies(query, hits) {
         if (!representative)
             continue;
         collapsedFamilies.push(representative);
-        const supportCandidates = [group.root, ...group.references].filter((entry) => {
+        const supportCandidates = [group.root, ...group.references]
+            .filter((entry) => {
             return entry !== undefined && entry.hit.ref !== representative.hit.ref;
+        })
+            .sort((a, b) => {
+            if (a === group.root)
+                return -1;
+            if (b === group.root)
+                return 1;
+            return a.hit.ref.localeCompare(b.hit.ref);
         });
         for (const support of supportCandidates) {
             appendCurateSupportRef(supportRefsByRef, representative.hit.ref, {

package/dist/commands/sources/bundle-cli.js

@@ -118,7 +118,7 @@ const removeCommand = defineJsonCommand({
     },
 });
 const updateCommand = defineJsonCommand({
-    meta: { name: "update", description: "Stage, audit, and update one or all remote bundles" },
+    meta: { name: "update", description: "Refresh one or all configured bundles and reconcile their index" },
     args: {
         target: { type: "positional", description: "Bundle to update (id or ref)", required: false },
         all: { type: "boolean", description: "Update all configured bundles and report each outcome", default: false },