akm-cli 0.9.0-rc.1 → 0.9.0-rc.2

package/dist/indexer/passes/metadata.js

@@ -6,6 +6,7 @@ import path from "node:path";
 import { deriveCanonicalAssetName, deriveCanonicalAssetNameFromStashRoot, isRelevantAssetFile, } from "../../core/asset/asset-spec.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { asNonEmptyString, isAssetType, writeFileAtomic } from "../../core/common.js";
+import { loadUserConfig } from "../../core/config/config.js";
 import { isVerbose, warn } from "../../core/warn.js";
 import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "../walk/file-context.js";
 import { applyMetadataContributors } from "./metadata-contributors.js";
@@ -182,6 +183,12 @@ export function validateStashEntry(entry) {
     const sources = normalizeNonEmptyStringList(e.sources);
     if (sources)
         result.sources = sources;
+    // SPEC-6: `category` must survive the whitelist or .stash.json-declared
+    // facts lose their convention/meta marker on the round-trip. Non-string
+    // values are dropped, not coerced.
+    if (typeof e.category === "string" && e.category.trim().length > 0) {
+        result.category = e.category.trim();
+    }
     if (typeof e.beliefState === "string" && e.beliefState.trim().length > 0) {
         result.beliefState = e.beliefState.trim();
     }
@@ -218,6 +225,12 @@ export function validateStashEntry(entry) {
     if (typeof e.derivedFrom === "string" && e.derivedFrom.trim().length > 0) {
         result.derivedFrom = e.derivedFrom.trim();
     }
+    // SPEC-8: `bodyOpening` must survive the whitelist so entries round-tripped
+    // through `.stash.json` keep their captured opening. Preserved verbatim —
+    // the extractor already trimmed and capped it at capture time.
+    if (typeof e.bodyOpening === "string" && e.bodyOpening.trim().length > 0) {
+        result.bodyOpening = e.bodyOpening;
+    }
     if (typeof e.scope === "object" && e.scope !== null && !Array.isArray(e.scope)) {
         const scope = normalizeScopeObject(e.scope);
         if (scope)
@@ -342,6 +355,12 @@ export function applyCuratedFrontmatter(entry, fmData) {
     const quality = asNonEmptyString(fmData.quality);
     if (quality)
         entry.quality = normalizeQuality(quality);
+    // SPEC-6 capture step: the `category:` frontmatter key (e.g. `convention`,
+    // `meta` on facts) must land on the indexed entry so category-keyed
+    // policies can see it. Trimmed; blank/non-string values are ignored.
+    const category = asNonEmptyString(fmData.category);
+    if (category)
+        entry.category = category;
     const beliefState = asNonEmptyString(fmData.beliefState);
     if (beliefState)
         entry.beliefState = beliefState;
@@ -805,6 +824,192 @@ export function isEnrichmentComplete(entry) {
     const hasSearchHints = Array.isArray(entry.searchHints) && entry.searchHints.length > 0;
     return hasDescription && hasTags && hasSearchHints;
 }
+// ── Body-opening extraction (stash-conventions SPEC-8) ──────────────────────
+/**
+ * Maximum length of a captured self-situating body opening. Bounds index-size
+ * growth and keeps a single verbose opening from dominating the low-weight
+ * `content` FTS column.
+ */
+export const BODY_OPENING_MAX_CHARS = 280;
+/**
+ * Minimum characters retained when the cap truncates at a word boundary. A
+ * boundary cut that would retain less than this falls back to a hard cut, so
+ * one pathological long token cannot gut the capture.
+ */
+const BODY_OPENING_MIN_RETAINED_CHARS = 250;
+/**
+ * True when `index.indexBodyOpening` is enabled in the user config.
+ *
+ * The gate is the GLOBAL user config, read directly by the metadata pass so
+ * every indexing entry point (stash walk, flat walk, write-path indexing)
+ * honors the flag without parameter plumbing. Fail-open: an unreadable or
+ * invalid config must never break indexing (CLI entry points surface config
+ * errors loudly on their own), so any load failure reads as "off".
+ */
+function isBodyOpeningIndexingEnabled() {
+    try {
+        return loadUserConfig().index?.indexBodyOpening === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Locate a leading nested frontmatter block in a body: up to three blank
+ * lines, then a `---` line, closed by a later `---` line. Mirrors the
+ * base-linter's `parseInnerFrontmatterBlock` recognition — when `akm
+ * remember` wraps a session-capture hook's file in its own frontmatter, the
+ * hook's `---\nakm_memory_kind: …\n---` block survives at the top of the
+ * body. Returns the open/close line indexes, or `null` when no block opens.
+ * Location only — callers apply their own interior checks (marker scan in
+ * {@link hasSessionMemoryMarker}, shape test in {@link isFrontmatterShaped}).
+ */
+function findInnerFrontmatterBlock(lines) {
+    let i = 0;
+    while (i < lines.length && i < 3 && lines[i].trim() === "")
+        i += 1;
+    if (lines[i] !== "---")
+        return null;
+    for (let j = i + 1; j < lines.length; j += 1) {
+        if (lines[j] === "---")
+            return { open: i, close: j };
+    }
+    return null;
+}
+/**
+ * True when the document carries the session-capture `akm_memory_kind`
+ * marker — in the outer frontmatter data OR in a nested inner block at the
+ * top of the body (both producer layouts exist; see base-linter's
+ * `extractFrontmatterRefs`). Session bodies are raw transcripts, never a
+ * self-situating opening.
+ */
+function hasSessionMemoryMarker(fmData, body) {
+    if (typeof fmData.akm_memory_kind === "string")
+        return true;
+    const lines = body.split(/\r?\n/);
+    const block = findInnerFrontmatterBlock(lines);
+    if (!block)
+        return false;
+    for (let i = block.open + 1; i < block.close; i += 1) {
+        if (/^akm_memory_kind:\s*\S/.test(lines[i]))
+            return true;
+    }
+    return false;
+}
+/**
+ * True when the interior of a candidate inner block (located by
+ * {@link findInnerFrontmatterBlock}) actually reads as YAML frontmatter:
+ * every line is blank, indented (a continuation or nested value), or shaped
+ * like a top-level `key:` mapping entry. Ordinary prose bracketed by two
+ * thematic-break `---` lines fails this test, so a decorative opening
+ * callout is treated as the paragraph it is instead of being discarded
+ * (review finding on SPEC-8 — the block finder alone accepts ANY content up
+ * to an arbitrarily distant closing `---`).
+ */
+function isFrontmatterShaped(lines, block) {
+    for (let i = block.open + 1; i < block.close; i += 1) {
+        const line = lines[i];
+        if (line.trim() === "")
+            continue;
+        if (/^\s/.test(line))
+            continue; // indented continuation / nested value
+        if (/^[A-Za-z0-9_.-]+:(\s|$)/.test(line))
+            continue; // top-level key
+        return false;
+    }
+    return true;
+}
+/**
+ * Extract the first prose paragraph of a markdown body (frontmatter already
+ * stripped by the caller): skip blank lines, ATX headings, setext `=`
+ * underlines (discarding the heading text above them), thematic breaks,
+ * fenced code blocks (``` or ~~~, including their contents), and a leading
+ * nested frontmatter block — skipped only when its interior is actually
+ * frontmatter-shaped, so prose wrapped in decorative `---` lines is still
+ * captured; then collect consecutive non-blank lines until the paragraph
+ * ends. Deliberate asymmetry: a `---` row after captured prose ENDS the
+ * paragraph and keeps it (favoring the callout/thematic-break reading over
+ * CommonMark's setext-H2), while a `=+` row can only be a setext underline
+ * and so discards the pending lines as heading text. The result is capped at
+ * {@link BODY_OPENING_MAX_CHARS} chars — truncated at the last word boundary
+ * that still retains a substantial prefix, with a trailing ellipsis. Returns
+ * `undefined` when the body has no prose (frontmatter-only files,
+ * headings/fences-only bodies).
+ */
+export function extractBodyOpening(body) {
+    const lines = body.split(/\r?\n/);
+    const innerBlock = findInnerFrontmatterBlock(lines);
+    const start = innerBlock && isFrontmatterShaped(lines, innerBlock) ? innerBlock.close + 1 : 0;
+    const paragraph = [];
+    let inFence = false;
+    let fenceChar = "";
+    let inHtmlComment = false;
+    for (let i = start; i < lines.length; i += 1) {
+        const trimmed = lines[i].trim();
+        const fenceMatch = trimmed.match(/^(`{3,}|~{3,})/);
+        if (inFence) {
+            // Fence interiors are never prose (and may be secrets-adjacent command
+            // text); skip until the matching closing marker.
+            if (fenceMatch && fenceMatch[1][0] === fenceChar)
+                inFence = false;
+            continue;
+        }
+        if (inHtmlComment) {
+            // Comment interiors are machinery (the skeleton convention facts open
+            // with a <!-- SOFT guidance --> block), never orientation prose.
+            if (trimmed.includes("-->"))
+                inHtmlComment = false;
+            continue;
+        }
+        if (fenceMatch) {
+            if (paragraph.length > 0)
+                break; // a fence ends an open paragraph
+            inFence = true;
+            fenceChar = fenceMatch[1][0];
+            continue;
+        }
+        if (trimmed.startsWith("<!--")) {
+            if (paragraph.length > 0)
+                break; // a comment ends an open paragraph
+            if (!trimmed.includes("-->"))
+                inHtmlComment = true;
+            continue;
+        }
+        if (/^=+$/.test(trimmed)) {
+            // A row of `=` is a setext H1 underline: the pending lines are heading
+            // text, not prose — discard them and keep searching. (A bare `=` row
+            // with nothing pending is skipped like any other non-prose divider.)
+            paragraph.length = 0;
+            continue;
+        }
+        const isBlank = trimmed === "";
+        const isHeading = /^#{1,6}(\s|$)/.test(trimmed);
+        const isThematicBreak = /^(-{3,}|\*{3,}|_{3,})$/.test(trimmed);
+        if (isBlank || isHeading || isThematicBreak) {
+            if (paragraph.length > 0)
+                break; // paragraph complete
+            continue; // still searching for the first prose line
+        }
+        paragraph.push(trimmed);
+    }
+    const text = paragraph.join("\n");
+    if (!text)
+        return undefined;
+    if (text.length <= BODY_OPENING_MAX_CHARS)
+        return text;
+    // Cap: prefer a word-boundary cut (never mid-token), but only when it keeps
+    // a substantial prefix; append a one-char ellipsis inside the budget.
+    const slice = text.slice(0, BODY_OPENING_MAX_CHARS - 1);
+    const lastBoundary = Math.max(slice.lastIndexOf(" "), slice.lastIndexOf("\n"), slice.lastIndexOf("\t"));
+    let cut = lastBoundary >= BODY_OPENING_MIN_RETAINED_CHARS ? slice.slice(0, lastBoundary) : slice;
+    // slice() counts UTF-16 code units, so the no-boundary fallback can end on
+    // the high half of a surrogate pair — a lone surrogate that corrupts the
+    // FTS/embedding text. Drop it rather than emit invalid UTF-16.
+    const lastCode = cut.charCodeAt(cut.length - 1);
+    if (lastCode >= 0xd800 && lastCode <= 0xdbff)
+        cut = cut.slice(0, -1);
+    return `${cut.trimEnd()}…`;
+}
 // ── Metadata Generation ─────────────────────────────────────────────────────
 /**
  * Shared pipeline (steps 2-6) for building a single StashEntry from a file.
@@ -861,6 +1066,17 @@ async function buildEntryFromFile(file, assetType, canonicalName, dirPath, pkgMe
             entry.parameters = fmParams;
         // Pass wiki-pattern frontmatter through onto the entry
         applyWikiFrontmatter(entry, parsed.data);
+        // Stash-organization conventions (SPEC-8): config-gated capture of the
+        // self-situating body opening. Default off — enabling it changes indexed
+        // text (collapse-detector canary baselines shift, and embeddings for
+        // already-embedded entries are NOT regenerated; see docs/configuration.md).
+        // Session-kind memories are raw transcripts and are never captured;
+        // secrets never reach this branch (guard above) and env files are not .md.
+        if (isBodyOpeningIndexingEnabled() && !hasSessionMemoryMarker(parsed.data, parsed.content)) {
+            const bodyOpening = extractBodyOpening(parsed.content);
+            if (bodyOpening)
+                entry.bodyOpening = bodyOpening;
+        }
         // Extract parameters from template placeholders ($1, $ARGUMENTS, {{named}})
         if (entry.type === "command") {
             const cmdParams = extractCommandParameters(parsed.content);
@@ -911,6 +1127,17 @@ async function buildEntryFromFile(file, assetType, canonicalName, dirPath, pkgMe
     if (!entry.tags || entry.tags.length === 0) {
         entry.tags = extractTagsFromPath(file, dirPath);
     }
+    // Stash-organization conventions (SPEC-2): directory (scope/domain) tokens
+    // always reach the tags column, even when the author set explicit tags, so
+    // nested assets keep the exact-tag ranking boost for their scope token.
+    // Derived from canonicalName (the ref subpath) rather than the filesystem
+    // path so the stash-walk and flat-walk indexing paths agree (the flat walk
+    // passes `path.dirname(file)` as dirPath, which strips directory segments
+    // from the fallback above). Filename tokens are deliberately NOT merged when
+    // explicit tags exist — they already live in the FTS name column and in
+    // aliases, and merging them would inflate exact-tag matches for every
+    // filename word. `normalizeTerms` below dedupes author-restated tokens.
+    entry.tags = [...(entry.tags ?? []), ...extractDirTagsFromName(canonicalName)];
     entry.tags = normalizeTerms(entry.tags ?? []);
     entry.aliases = mergeAliases(entry.aliases, buildAliases(canonicalName, entry.tags));
     // Search hints are only generated when LLM is configured (via enhanceStashWithLlm)
@@ -1127,3 +1354,26 @@ export function extractTagsFromPath(filePath, rootDir) {
     }
     return Array.from(tags);
 }
+/**
+ * Extract scope/domain tags from the DIRECTORY segments of a canonical asset
+ * name (the ref subpath — e.g. `"projectA/auth-tip"` → `["projecta"]`).
+ *
+ * Unlike {@link extractTagsFromPath} this never tokenizes the filename
+ * segment: it exists so a nested asset's directory (scope/domain) tokens can
+ * be merged into explicit author tags without dragging every filename word
+ * into exact-tag matching (SPEC-2, docs/design/stash-conventions-code-spec.md).
+ * Tokenization mirrors `extractTagsFromPath`: each segment splits on `-`/`_`/
+ * `.`, lowercased, single-character tokens dropped. A name with no directory
+ * segments yields no tags.
+ */
+export function extractDirTagsFromName(name) {
+    const tags = new Set();
+    for (const segment of name.split("/").slice(0, -1)) {
+        for (const token of segment.split(/[-_.]+/)) {
+            const clean = token.toLowerCase().trim();
+            if (clean && clean.length > 1)
+                tags.add(clean);
+        }
+    }
+    return Array.from(tags);
+}

package/dist/indexer/search/db-search.js

@@ -17,6 +17,7 @@ import fs from "node:fs";
 import { buildActionFromContributors, defaultActionContributors } from "../../core/action-contributors.js";
 import { makeAssetRef } from "../../core/asset/asset-ref.js";
 import { defaultRendererRegistry } from "../../core/asset/asset-registry.js";
+import { getAssetTypes } from "../../core/asset/asset-spec.js";
 import { getDbPath } from "../../core/paths.js";
 import { warn } from "../../core/warn.js";
 import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.js";
@@ -25,6 +26,7 @@ import { ensureIndex } from "../ensure-index.js";
 import { collectGraphRelatedHit, computeGraphBoost, loadGraphBoostContext, } from "../graph/graph-boost.js";
 import { isProposedQuality } from "../passes/metadata.js";
 import { resolveProjectContext } from "../walk/project-context.js";
+import { parseRefPrefixQuery } from "./fts-query.js";
 import { applyRankingRules, combineSearchScores, normalizeFtsScores } from "./ranking.js";
 import { enrichSearchHit } from "./search-hit-enrichers.js";
 import { buildEditHint, findSourceForPath, isEditable } from "./search-source.js";
@@ -169,58 +171,53 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     // `includeExcludedTypes`. When the config key is ABSENT a built-in default of
     // ['session'] is applied; an explicit empty list disables exclusion.
     const defaultExcludes = searchType === "any" && !includeExcludedTypes ? (config.search?.defaultExcludeTypes ?? ["session"]) : [];
+    // SPEC-4 — ref-prefix queries (`<type>:` / `<type>:<prefix>/`) translate to
+    // a typed enumeration narrowed by name prefix, instead of degenerating into
+    // the AND-token FTS query their sanitized form would produce ("memory
+    // projecta" — noise). The branch fires only on the untyped path: an explicit
+    // `--type` flag expresses stronger intent and wins. The PARSED type is
+    // itself explicit intent, so `defaultExcludeTypes` does not apply — a bare
+    // `session:` enumerates sessions exactly like `--type session` does.
+    const refPrefix = searchType === "any" ? parseRefPrefixQuery(query, getAssetTypes()) : null;
+    if (refPrefix) {
+        return enumerateEntries({
+            db,
+            query,
+            typeFilter: refPrefix.type,
+            excludeTypes: [],
+            namePrefix: refPrefix.namePrefix,
+            limit,
+            stashDir,
+            allSourceDirs,
+            sources,
+            config,
+            rendererRegistry,
+            filters,
+            includeProposed,
+            beliefFilter,
+            restrictToSources,
+        });
+    }
     // Empty queries — including ones that sanitize down to no searchable FTS
     // tokens such as "." — should enumerate matching entries instead of
     // returning an empty result set from FTS.
     if (!hasSearchableTokens) {
-        const typeFilter = searchType === "any" ? undefined : searchType;
-        const allEntries = getAllEntries(db, typeFilter, defaultExcludes);
-        // Deduplicate by file path — multiple entries can share the same file
-        const seenFilePaths = new Set();
-        const uniqueEntries = allEntries.filter((ie) => {
-            if (seenFilePaths.has(ie.filePath))
-                return false;
-            seenFilePaths.add(ie.filePath);
-            return true;
-        });
-        // Source filter: when the caller narrowed `sources` via `--source <name>`,
-        // drop entries whose filePath does not live under any of the requested
-        // sources. The FTS index spans every configured source, so without this
-        // filter a narrowed --source request would still leak results.
-        const sourceFiltered = restrictToSources
-            ? uniqueEntries.filter((ie) => findSourceForPath(ie.filePath, sources) !== undefined)
-            : uniqueEntries;
-        // Scope filter: drop entries whose stored scope does not satisfy every
-        // supplied scope key. Filtering happens BEFORE the limit slice so a
-        // restrictive filter still returns up to `limit` results.
-        const scopeFiltered = filters
-            ? sourceFiltered.filter((ie) => entryMatchesScope(ie.entry.scope, filters))
-            : sourceFiltered;
-        // Proposed-quality filter (v1 spec §4.2): exclude entries with
-        // `quality: "proposed"` unless the caller explicitly opts in.
-        const qualityFiltered = includeProposed
-            ? scopeFiltered
-            : scopeFiltered.filter((ie) => !isProposedQuality(ie.entry.quality));
-        // 03-R3: derived twins inherit their base's demoting belief state here too,
-        // so the belief FILTER (and the reported hit state) stays consistent on the
-        // enumerate/browse path — not only on the FTS-scored path below.
-        inheritDerivedTwinBeliefStates(db, qualityFiltered);
-        const beliefFiltered = qualityFiltered.filter((ie) => matchBeliefFilter(ie.entry.beliefState, beliefFilter));
-        const selected = beliefFiltered.slice(0, limit);
-        const hits = await Promise.all(selected.map((ie) => buildDbHit({
-            entry: ie.entry,
-            path: ie.filePath,
-            score: 1,
+        return enumerateEntries({
+            db,
             query,
-            rankingMode: "fts",
-            defaultStashDir: stashDir,
+            typeFilter: searchType === "any" ? undefined : searchType,
+            excludeTypes: defaultExcludes,
+            limit,
+            stashDir,
             allSourceDirs,
             sources,
             config,
             rendererRegistry,
-            db,
-        })));
-        return { hits };
+            filters,
+            includeProposed,
+            beliefFilter,
+            restrictToSources,
+        });
     }
     // Start the async embedding request without awaiting, then run FTS
     // synchronously while the HTTP/local embedding request is in-flight.
@@ -323,8 +320,14 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     // Drop semantic-only hits (cosine-only, no FTS match) whose score falls
     // below the configured floor. FTS hits and hybrid hits are always kept.
     // Default floor: 0.2. Set search.minScore = 0 in config to disable.
+    // Judged on the PRE-ceiling score when a demoting belief state clamped the
+    // item (`preCeilingScore`): the belief ceilings can sit below this floor
+    // (archived 0.15 < 0.2), and a demotion must rank the hit last, not
+    // silently remove a result that would otherwise have listed.
     const minScore = config.search?.minScore ?? 0.2;
-    const preFilter = minScore > 0 ? scored.filter((item) => item.rankingMode !== "semantic" || item.score >= minScore) : scored;
+    const preFilter = minScore > 0
+        ? scored.filter((item) => item.rankingMode !== "semantic" || (item.preCeilingScore ?? item.score) >= minScore)
+        : scored;
     // Deterministic tiebreaker on equal scores.
     //
     // CRITICAL: sort on the SAME clamped+rounded value the user sees (see the
@@ -393,6 +396,70 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     }));
     return { embedMs, rankMs, hits };
 }
+// ── Enumeration (browse) path ────────────────────────────────────────────────
+/**
+ * Enumerate index entries without FTS scoring — the browse path shared by
+ * empty/unsearchable queries and SPEC-4 ref-prefix queries (`<type>:` /
+ * `<type>:<prefix>/`). Applies the same post-ranking filters as the scored
+ * path (source narrowing, scope, proposed-quality, belief) before the limit
+ * slice. Hits carry the fixed browse score 1 in insertion order — this is a
+ * deterministic listing, not a relevance ranking.
+ */
+async function enumerateEntries(opts) {
+    const { db, query, sources, config, rendererRegistry, filters, beliefFilter } = opts;
+    const allEntries = getAllEntries(db, opts.typeFilter, opts.excludeTypes);
+    // SPEC-4: narrow to the requested subtree. `startsWith` on the full
+    // slash-retaining prefix is exact — "projecta/" cannot match a sibling
+    // "projectalpha/…" scope.
+    const namePrefix = opts.namePrefix?.toLowerCase() ?? "";
+    const prefixFiltered = namePrefix.length > 0 ? allEntries.filter((ie) => ie.entry.name.toLowerCase().startsWith(namePrefix)) : allEntries;
+    // Deduplicate by file path — multiple entries can share the same file
+    const seenFilePaths = new Set();
+    const uniqueEntries = prefixFiltered.filter((ie) => {
+        if (seenFilePaths.has(ie.filePath))
+            return false;
+        seenFilePaths.add(ie.filePath);
+        return true;
+    });
+    // Source filter: when the caller narrowed `sources` via `--source <name>`,
+    // drop entries whose filePath does not live under any of the requested
+    // sources. The FTS index spans every configured source, so without this
+    // filter a narrowed --source request would still leak results.
+    const sourceFiltered = opts.restrictToSources
+        ? uniqueEntries.filter((ie) => findSourceForPath(ie.filePath, sources) !== undefined)
+        : uniqueEntries;
+    // Scope filter: drop entries whose stored scope does not satisfy every
+    // supplied scope key. Filtering happens BEFORE the limit slice so a
+    // restrictive filter still returns up to `limit` results.
+    const scopeFiltered = filters
+        ? sourceFiltered.filter((ie) => entryMatchesScope(ie.entry.scope, filters))
+        : sourceFiltered;
+    // Proposed-quality filter (v1 spec §4.2): exclude entries with
+    // `quality: "proposed"` unless the caller explicitly opts in.
+    const qualityFiltered = opts.includeProposed
+        ? scopeFiltered
+        : scopeFiltered.filter((ie) => !isProposedQuality(ie.entry.quality));
+    // 03-R3: derived twins inherit their base's demoting belief state here too,
+    // so the belief FILTER (and the reported hit state) stays consistent on the
+    // enumerate/browse path — not only on the FTS-scored path.
+    inheritDerivedTwinBeliefStates(db, qualityFiltered);
+    const beliefFiltered = qualityFiltered.filter((ie) => matchBeliefFilter(ie.entry.beliefState, beliefFilter));
+    const selected = beliefFiltered.slice(0, opts.limit);
+    const hits = await Promise.all(selected.map((ie) => buildDbHit({
+        entry: ie.entry,
+        path: ie.filePath,
+        score: 1,
+        query,
+        rankingMode: "fts",
+        defaultStashDir: opts.stashDir,
+        allSourceDirs: opts.allSourceDirs,
+        sources,
+        config,
+        rendererRegistry,
+        db,
+    })));
+    return { hits };
+}
 /**
  * 03-R3: let each `.derived` twin inherit its base memory's demoting belief
  * state for this ranking pass, so a stale flag-free twin is demoted like its

package/dist/indexer/search/fts-query.js

@@ -6,6 +6,8 @@
  *
  * These transform a raw user query into an FTS5-safe MATCH expression. They
  * touch no database state, so they are unit-testable with zero DB setup.
+ * `parseRefPrefixQuery` is the one non-FTS helper: it decides whether a raw
+ * query should bypass FTS entirely (SPEC-4 ref-prefix enumeration).
  */
 /**
  * Sanitize a raw user query into an FTS5-safe implicit-AND expression.
@@ -49,3 +51,42 @@ export function buildPrefixQuery(ftsQuery) {
         return null;
     return prefixTokens.join(" ");
 }
+/**
+ * SPEC-4 — parse a ref-prefix query (`akm search "<type>:<prefix>/"`).
+ *
+ * Decides whether a raw query is a typed subtree-enumeration request rather
+ * than an ordinary keyword search. Matching is deliberately conservative: the
+ * trimmed query must be EXACTLY
+ *
+ *   - `<known-type>:`           → enumerate the whole type (namePrefix `""`), or
+ *   - `<known-type>:<prefix>/`  → enumerate names under `<prefix>/`.
+ *
+ * The trailing slash is REQUIRED for a non-empty prefix — and is RETAINED in
+ * the returned `namePrefix` — so that a plain `entry.name.startsWith(namePrefix)`
+ * check gives exact `/`-boundary subtree semantics (`"projecta/"` cannot match
+ * a sibling `projectalpha/…` scope). Bare refs like `memory:a/b` therefore
+ * stay ordinary searches (resolving one ref is `akm show` territory), and any
+ * interior whitespace disqualifies (prose mentioning a ref is still prose).
+ *
+ * `knownTypes` is passed in by the caller (e.g. `getAssetTypes()`) to keep
+ * this module dependency-free.
+ *
+ * Returns `null` when the query is not a ref-prefix request.
+ */
+export function parseRefPrefixQuery(query, knownTypes) {
+    const trimmed = query.trim();
+    if (trimmed.length === 0 || /\s/.test(trimmed))
+        return null;
+    const colon = trimmed.indexOf(":");
+    if (colon <= 0)
+        return null;
+    const type = trimmed.slice(0, colon);
+    if (!knownTypes.includes(type))
+        return null;
+    const rest = trimmed.slice(colon + 1);
+    if (rest === "")
+        return { type, namePrefix: "" };
+    if (rest.endsWith("/"))
+        return { type, namePrefix: rest };
+    return null;
+}

package/dist/indexer/search/ranking-contributors.js

@@ -61,6 +61,54 @@ function beliefStateBoost(item) {
         return 0.06;
     return 0;
 }
+/**
+ * Post-boost score ceilings for the demoting belief states (SPEC-5,
+ * stash-conventions-code-spec.md — corrections demotion).
+ *
+ * Why the additive {@link beliefStateBoost} penalties alone are not enough:
+ * keyword base scores are min-max normalized into [0.3, 1.0]
+ * (`normalizeFtsScores`), so the spread between the best FTS hit and its
+ * runner-up can be as large as 0.7 — and the boost sum then MULTIPLIES the
+ * base (`score *= 1 + boostSum`, {@link applyScoreContributors}). A
+ * superseded incumbent that is the best keyword match for a query therefore
+ * stays clamp-pinned at 1.0 above its own correction no matter what additive
+ * penalty it receives — defeating the corrections pattern's point ("so the
+ * ranker demotes the stale version instead of letting it outrank your fix").
+ *
+ * The ceilings guarantee the demotion while keeping flagged entries VISIBLE:
+ * un-demoted keyword hits floor at a 0.3 base, so any un-demoted hit outranks
+ * a ceilinged one; demoted entries still list (belief FILTERING stays a
+ * separate opt-in axis, `--belief`), and scores already below a ceiling keep
+ * their relative ordering. Ceiling order mirrors the additive-penalty
+ * severity order pinned in tests/belief-state-phase1a.test.ts:
+ * deprecated (mildest) > superseded > contradicted > archived.
+ */
+const BELIEF_STATE_SCORE_CEILINGS = {
+    deprecated: 0.28,
+    superseded: 0.25,
+    contradicted: 0.2,
+    archived: 0.15,
+};
+/**
+ * Clamp a ranked entry's FINAL score (after every additive and utility boost)
+ * to its demoting belief state's ceiling. No-op for `asserted`/`active`/unset
+ * entries. Applied once per item at the end of `applyRankingRules` so sort
+ * order and displayed scores stay consistent (single scoring pipeline).
+ *
+ * When the ceiling clamps, the pre-clamp score is recorded as
+ * `preCeilingScore` so db-search's semantic-only `minScore` floor can judge
+ * the hit by what it would have scored WITHOUT the demotion — a ceiling below
+ * the floor (archived 0.15 < default minScore 0.2) must demote a hit to last
+ * place, never silently drop it from the results.
+ */
+export function applyBeliefStateScoreCeiling(item) {
+    const state = item.entry.beliefState;
+    const ceiling = state !== undefined ? BELIEF_STATE_SCORE_CEILINGS[state] : undefined;
+    if (ceiling !== undefined && item.score > ceiling) {
+        item.preCeilingScore = item.score;
+        item.score = ceiling;
+    }
+}
 const exactNameRankingContributor = {
     name: "exact-name-ranking",
     appliesTo: () => true,