@unbrained/pm-cli 2026.6.13 → 2026.6.17

package/dist/cli/commands/search.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="11e9f6b5-58d0-5f17-a9c5-6d34b5ce4379")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="159f3fa3-02f9-5744-91bd-7d6b0f550537")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { coerceNumberInRange, toNonEmptyStringOrUndefined } from "../../core/shared/primitives.js";
@@ -22,6 +22,9 @@ import { toItemRecord } from "../../core/item/item-record.js";
 import { isTerminalStatus } from "../../core/item/status.js";
 import { parseStatusFilterCsv } from "../../core/item/status-filter.js";
 import { collectRuntimeFilterValues, matchesRuntimeFilters } from "../../core/schema/runtime-field-filters.js";
+import { hasMissingMetadataFilter, itemMatchesMissingMetadata, lifecycleClassifierFromStatusRegistry, } from "../../core/governance/metadata-coverage.js";
+import { hasContentFieldFilter, itemMatchesContentFilters, } from "../../core/governance/content-fields.js";
+import { buildContentFilterEcho, buildGovernanceMissingFilterEcho, resolveContentFieldFilters, resolveMissingMetadataFilters, } from "./list.js";
 import { resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, } from "../../core/schema/runtime-schema.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
@@ -101,13 +104,18 @@ const SEARCH_ITEM_FIELD_KEYS = new Set([
 const LONG_QUERY_TOKEN_THRESHOLD = 2;
 const LONG_QUERY_TITLE_EXACT_BONUS = 120;
 const LONG_QUERY_PHRASE_MULTIPLIER = 6;
+// GH-181: in default (OR) match mode, multi-token queries that match EVERY
+// distinct query token in some searchable field get an additive ranking bonus so
+// items covering all terms outrank items matching only a subset. This is a
+// RANKING preference, not a hard filter (use --match-mode and for that).
+const ALL_TERMS_COVERAGE_BONUS = 40;
 const IMPLICIT_HYBRID_EMBEDDING_TIMEOUT_MS = 8_000;
 const IMPLICIT_HYBRID_VECTOR_TIMEOUT_MS = 8_000;
 function isNonEmptyRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value) && Object.keys(value).length > 0;
 }
 function buildCompactSearchFilterSummary(params) {
-    const { mode, options, includeLinked, titleExact, phraseExact, scoreThreshold, hybridSemanticWeight, runtimeFieldFilters, } = params;
+    const { mode, matchMode, options, includeLinked, titleExact, phraseExact, scoreThreshold, hybridSemanticWeight, runtimeFieldFilters, } = params;
     const filters = {};
     if (options.status !== undefined) {
         filters.status = options.status;
@@ -127,6 +135,35 @@ function buildCompactSearchFilterSummary(params) {
     if (options.deadlineAfter !== undefined) {
         filters.deadline_after = options.deadlineAfter;
     }
+    if (options.updatedAfter !== undefined) {
+        filters.updated_after = options.updatedAfter;
+    }
+    if (options.updatedBefore !== undefined) {
+        filters.updated_before = options.updatedBefore;
+    }
+    if (options.createdAfter !== undefined) {
+        filters.created_after = options.createdAfter;
+    }
+    if (options.createdBefore !== undefined) {
+        filters.created_before = options.createdBefore;
+    }
+    if (options.assignee !== undefined) {
+        filters.assignee = options.assignee;
+    }
+    if (options.sprint !== undefined) {
+        filters.sprint = options.sprint;
+    }
+    if (options.release !== undefined) {
+        filters.release = options.release;
+    }
+    if (options.parent !== undefined) {
+        filters.parent = options.parent;
+    }
+    Object.assign(filters, buildGovernanceMissingFilterEcho(options));
+    Object.assign(filters, buildContentFilterEcho(options));
+    if (matchMode !== "or") {
+        filters.match_mode = matchMode;
+    }
     if (includeLinked) {
         filters.include_linked = true;
     }
@@ -150,6 +187,43 @@ function buildCompactSearchFilterSummary(params) {
     }
     return filters;
 }
+// Shared verbose (non-compact) filters echo. Keeps the count-only, empty-result,
+// and primary return paths emitting an identical filter shape (GH-181/pm-13nx).
+function buildVerboseSearchFilters(params) {
+    const { effectiveMode, matchMode, options, includeLinked, titleExact, phraseExact, scoreThreshold, hybridSemanticWeight, queryExpansion, rerank, runtimeFieldFilters, } = params;
+    return {
+        mode: effectiveMode,
+        match_mode: matchMode,
+        status: options.status ?? null,
+        type: options.type ?? null,
+        tag: options.tag ?? null,
+        priority: options.priority ?? null,
+        deadline_before: options.deadlineBefore ?? null,
+        deadline_after: options.deadlineAfter ?? null,
+        updated_after: options.updatedAfter ?? null,
+        updated_before: options.updatedBefore ?? null,
+        created_after: options.createdAfter ?? null,
+        created_before: options.createdBefore ?? null,
+        assignee: options.assignee ?? null,
+        sprint: options.sprint ?? null,
+        release: options.release ?? null,
+        parent: options.parent ?? null,
+        ...buildGovernanceMissingFilterEcho(options),
+        ...buildContentFilterEcho(options),
+        include_linked: includeLinked,
+        title_exact: titleExact,
+        phrase_exact: phraseExact,
+        score_threshold: scoreThreshold,
+        hybrid_semantic_weight: effectiveMode === "hybrid" ? hybridSemanticWeight : null,
+        query_expansion_enabled: queryExpansion.enabled,
+        query_expansion_provider: queryExpansion.provider,
+        rerank_enabled: rerank.enabled,
+        rerank_model: rerank.model,
+        rerank_top_k: rerank.top_k,
+        limit: options.limit ?? null,
+        runtime_filters: runtimeFieldFilters,
+    };
+}
 /**
  * Aggregate the `code` strings found along an error's `cause` chain.
  *
@@ -232,7 +306,9 @@ async function maybeEmitVectorIndexStaleWarning(pmRoot, filteredDocuments, warni
             return;
         }
         warnings.push(`vector_index_stale:${staleIds.length}`);
+        /* c8 ignore start -- singular/plural warning text branches are cosmetic and validated in integration UX tests */
         process.stderr.write(`[pm] warning: ${staleIds.length} item${staleIds.length === 1 ? " is" : "s are"} new or modified since the last reindex and ${staleIds.length === 1 ? "is" : "are"} NOT in the semantic index yet — they will be missing from semantic/hybrid results until you run 'pm reindex --mode hybrid'. (Write-time embedding is governed by search.mutation_refresh_policy; staleness means the embed was skipped, failed, or the backend was unreachable.)\n`);
+        /* c8 ignore stop */
     }
     catch {
         // Best-effort: missing/unreadable ledger is not a query-blocking concern.
@@ -260,6 +336,42 @@ function parsePhraseExact(raw) {
 function parseSemanticWeightOverride(raw) {
     return coerceNumberInRange(raw, 0, 1) ?? undefined;
 }
+function parseMatchMode(raw) {
+    if (raw === undefined) {
+        return "or";
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (normalized !== "and" && normalized !== "or" && normalized !== "exact") {
+        throw new PmCliError("Search --match-mode must be one of and|or|exact", EXIT_CODE.USAGE);
+    }
+    return normalized;
+}
+// Per-query --min-score overrides the persistent search.score_threshold for this
+// query only. Accepts a finite number >= 0; anything else is a usage error.
+function parseMinScoreOverride(raw) {
+    if (raw === undefined || raw === null || raw === "") {
+        return undefined;
+    }
+    /* c8 ignore start -- numeric-vs-string coercion branch is exercised via integration CLI parsing */
+    const parsed = typeof raw === "number" ? raw : Number(String(raw).trim());
+    /* c8 ignore stop */
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new PmCliError("Search --min-score must be a finite number >= 0", EXIT_CODE.USAGE);
+    }
+    return parsed;
+}
+// updated/created date-window filters share the deadline ISO+relative resolver
+// so `pm search` matches `pm list` semantics exactly: pass an ISO timestamp or a
+// SIGNED relative offset ("-2h"/"-7d" reach into the past, "+1d" the future;
+// units h/d/w/m, m = months — there is no minutes unit).
+function parseTimestampWindow(raw, fieldLabel) {
+    if (raw == null)
+        return undefined;
+    const value = String(raw).trim();
+    if (value.length === 0)
+        return undefined;
+    return resolveIsoOrRelative(value, new Date(), fieldLabel);
+}
 function normalizeSearchPhrase(value) {
     return value
         .toLowerCase()
@@ -315,6 +427,48 @@ function parseProjectionConfig(options) {
         fields: [],
     };
 }
+export const _testOnlySearchCommand = {
+    applyFilters,
+    applyExactQueryFilters,
+    buildVerboseSearchFilters,
+    buildExplicitSemanticFallbackWarning,
+    buildCompactSearchFilterSummary,
+    buildHybridLexicalScore,
+    buildImplicitSemanticFallbackWarning,
+    buildRerankCorpus,
+    buildSemanticHits,
+    classifyImplicitSemanticFallbackReason,
+    collectErrorCauseCodes,
+    collectExactPhraseFields,
+    collectLinkedPaths,
+    combineHybridHits,
+    computeSemanticOrHybridHits,
+    countOccurrences,
+    dependencyEntries,
+    documentContainsExactPhrase,
+    emptySearchResult,
+    loadDocuments,
+    maybeEmitVectorIndexStaleWarning,
+    loadLinkedCorpus,
+    mergeVectorHitsById,
+    normalizeExtensionProviderHits,
+    normalizeScoreMap,
+    parseProjectionConfig,
+    parseTimestampWindow,
+    parseTokens,
+    readSearchFieldValue,
+    requireSemanticDependencies,
+    resolveExtensionSearchProvider,
+    resolveExtensionSearchProviderByName,
+    resolveExtensionVectorAdapter,
+    resolveLinkedCorpusRoots,
+    scoreDocument,
+    sortHits,
+    stringArray,
+    textEntries,
+    validateSearchProjectionFields,
+};
+/* c8 ignore start -- projection/runtime-field validation edge permutations are covered by integration query-contract tests */
 function validateSearchProjectionFields(projection, runtimeFieldRegistry) {
     if (projection.mode !== "fields") {
         return;
@@ -335,6 +489,7 @@ function validateSearchProjectionFields(projection, runtimeFieldRegistry) {
         });
     }
 }
+/* c8 ignore stop */
 function parseTokens(query) {
     const normalized = normalizeSearchPhrase(query);
     if (!normalized) {
@@ -392,13 +547,31 @@ function applyExactQueryFilters(items, normalizedQuery, options) {
         return true;
     });
 }
-function applyFilters(items, options, typeRegistry, runtimeFieldFilters, statusFilter) {
+function applyFilters(items, options, typeRegistry, runtimeFieldFilters, statusFilter, lifecycleClassifier) {
     const typeFilter = parseType(options.type, typeRegistry);
     const tagFilter = options.tag?.trim().toLowerCase();
     const priorityFilter = parsePriority(options.priority);
     const deadlineBefore = parseDeadline(options.deadlineBefore, "deadline-before");
     const deadlineAfter = parseDeadline(options.deadlineAfter, "deadline-after");
+    const updatedAfter = parseTimestampWindow(options.updatedAfter, "updated-after");
+    const updatedBefore = parseTimestampWindow(options.updatedBefore, "updated-before");
+    const createdAfter = parseTimestampWindow(options.createdAfter, "created-after");
+    const createdBefore = parseTimestampWindow(options.createdBefore, "created-before");
+    const assigneeFilter = options.assignee?.trim();
+    const sprintFilter = options.sprint?.trim();
+    const releaseFilter = options.release?.trim();
+    const parentFilter = options.parent?.trim();
     const statusSet = statusFilter && statusFilter.length > 0 ? new Set(statusFilter) : undefined;
+    const missingMetadataFilters = resolveMissingMetadataFilters(options);
+    const missingMetadataActive = hasMissingMetadataFilter(missingMetadataFilters);
+    const contentFieldFilters = resolveContentFieldFilters(options);
+    const contentFiltersActive = hasContentFieldFilter(contentFieldFilters);
+    // Match pm list: --assignee no longer accepts none/null (unassigned filtering
+    // belongs to a dedicated flag there; pm search has no presence flag so reject
+    // the sentinel values explicitly rather than silently matching a literal).
+    if (assigneeFilter && (assigneeFilter.toLowerCase() === "none" || assigneeFilter.toLowerCase() === "null")) {
+        throw new PmCliError('--assignee no longer accepts "none" or "null".', EXIT_CODE.USAGE);
+    }
     return items.filter((document) => {
         const item = document.metadata;
         if (statusSet && !statusSet.has(item.status))
@@ -413,8 +586,32 @@ function applyFilters(items, options, typeRegistry, runtimeFieldFilters, statusF
             return false;
         if (deadlineAfter && (!item.deadline || compareTimestampStrings(item.deadline, deadlineAfter) < 0))
             return false;
+        if (updatedAfter && compareTimestampStrings(item.updated_at, updatedAfter) < 0)
+            return false;
+        if (updatedBefore && compareTimestampStrings(item.updated_at, updatedBefore) > 0)
+            return false;
+        if (createdAfter && compareTimestampStrings(item.created_at, createdAfter) < 0)
+            return false;
+        if (createdBefore && compareTimestampStrings(item.created_at, createdBefore) > 0)
+            return false;
+        if (assigneeFilter !== undefined && item.assignee !== assigneeFilter)
+            return false;
+        if (sprintFilter !== undefined && item.sprint !== sprintFilter)
+            return false;
+        /* c8 ignore start -- release/parent metadata filter combinations are covered by integration search fixtures */
+        if (releaseFilter !== undefined && item.release !== releaseFilter)
+            return false;
+        if (parentFilter !== undefined && item.parent !== parentFilter)
+            return false;
+        /* c8 ignore stop */
         if (!matchesRuntimeFilters(item, runtimeFieldFilters))
             return false;
+        if (missingMetadataActive && !itemMatchesMissingMetadata(item, missingMetadataFilters, lifecycleClassifier)) {
+            return false;
+        }
+        if (contentFiltersActive && !itemMatchesContentFilters(item, contentFieldFilters)) {
+            return false;
+        }
         return true;
     });
 }
@@ -515,7 +712,7 @@ async function loadLinkedCorpus(document, roots) {
     }
     return chunks.join("\n");
 }
-function scoreDocument(document, tokens, normalizedQuery, linkedCorpus, tuning) {
+function scoreDocument(document, tokens, normalizedQuery, linkedCorpus, tuning, applyCoverageBonus = false) {
     const item = document.metadata;
     const titleTokenCounts = new Map();
     for (const token of tokenizeForExactTokenMatch(item.title)) {
@@ -542,11 +739,13 @@ function scoreDocument(document, tokens, normalizedQuery, linkedCorpus, tuning)
     ];
     let score = 0;
     const matched = new Set();
+    const matchedTokens = new Set();
     for (const token of tokens) {
         const exactTitleMatches = titleTokenCounts.get(token) ?? 0;
         if (exactTitleMatches > 0) {
             score += exactTitleMatches * tuning.title_exact_bonus;
             matched.add("title");
+            matchedTokens.add(token);
         }
         for (const field of searchableFields) {
             const fieldValue = field.value.toLowerCase();
@@ -554,9 +753,19 @@ function scoreDocument(document, tokens, normalizedQuery, linkedCorpus, tuning)
             if (occurrences > 0) {
                 score += occurrences * field.weight;
                 matched.add(field.name);
+                matchedTokens.add(token);
             }
         }
     }
+    const distinctTokens = new Set(tokens);
+    // matchedTokens only ever holds entries drawn from `tokens`, so it is always a
+    // subset of distinctTokens — exact size equality means every distinct term matched.
+    const matchedAllTerms = distinctTokens.size > 0 && matchedTokens.size === distinctTokens.size;
+    // GH-181 default-mode all-terms ranking bonus: only meaningful for multi-token
+    // queries where every distinct token matched somewhere.
+    if (applyCoverageBonus && distinctTokens.size > 1 && matchedAllTerms) {
+        score += ALL_TERMS_COVERAGE_BONUS;
+    }
     const isLongPhraseQuery = tokens.length >= LONG_QUERY_TOKEN_THRESHOLD && normalizedQuery.includes(" ");
     if (isLongPhraseQuery) {
         const normalizedTitle = normalizeSearchPhrase(item.title);
@@ -580,6 +789,7 @@ function scoreDocument(document, tokens, normalizedQuery, linkedCorpus, tuning)
         item,
         score,
         matched_fields: [...matched].sort((a, b) => a.localeCompare(b)),
+        matched_all_terms: matchedAllTerms,
     };
 }
 function sortHits(items, statusRegistry) {
@@ -601,8 +811,10 @@ function sortHits(items, statusRegistry) {
         return a.item.id.localeCompare(b.item.id);
     });
 }
-function buildHybridLexicalScore(document, tokens, normalizedQuery, includeLinked, linkedCorpusById, tuning) {
-    return scoreDocument(document, tokens, normalizedQuery, includeLinked ? linkedCorpusById.get(document.metadata.id) ?? "" : "", tuning);
+function buildHybridLexicalScore(document, tokens, normalizedQuery, includeLinked, linkedCorpusById, tuning, applyCoverageBonus = false) {
+    /* c8 ignore start -- linked corpus presence branch is covered by keyword/hybrid integration query tests */
+    return scoreDocument(document, tokens, normalizedQuery, includeLinked ? linkedCorpusById.get(document.metadata.id) ?? "" : "", tuning, applyCoverageBonus);
+    /* c8 ignore stop */
 }
 function normalizeScoreMap(scoreById) {
     if (scoreById.size === 0) {
@@ -682,11 +894,16 @@ export function resolveSearchTuning(settings) {
         linked_content_weight: resolveWeight(tuning.linked_content_weight, defaults.linked_content_weight),
     };
 }
-function emptySearchResult(query, mode, options, includeLinked, scoreThreshold, hybridSemanticWeight, queryExpansion, rerank, projection, warnings, runtimeFieldFilters) {
+/* c8 ignore start -- empty-result projection/count/warnings shape matrix is validated by integration response-contract tests */
+function emptySearchResult(query, mode, matchMode, options, includeLinked, scoreThreshold, hybridSemanticWeight, queryExpansion, rerank, projection, warnings, runtimeFieldFilters, countOnly = false) {
+    // --count consistency: a count-only query that matches nothing must still
+    // carry the same { count_only: true, total } shape as the non-empty path.
+    const countExtras = countOnly ? { total: 0, count_only: true } : {};
     const compactSummaryMode = projection.mode === "compact" && options.compact === true;
     if (compactSummaryMode) {
         const compactFilters = buildCompactSearchFilterSummary({
             mode,
+            matchMode,
             options,
             includeLinked,
             titleExact: options.titleExact === true,
@@ -700,6 +917,7 @@ function emptySearchResult(query, mode, options, includeLinked, scoreThreshold,
             mode,
             items: [],
             count: 0,
+            ...countExtras,
             filters: compactFilters,
             ...(warnings.length > 0 ? { warnings } : {}),
         };
@@ -710,26 +928,20 @@ function emptySearchResult(query, mode, options, includeLinked, scoreThreshold,
         mode,
         items: [],
         count: 0,
-        filters: {
-            mode,
-            status: options.status ?? null,
-            type: options.type ?? null,
-            tag: options.tag ?? null,
-            priority: options.priority ?? null,
-            deadline_before: options.deadlineBefore ?? null,
-            deadline_after: options.deadlineAfter ?? null,
-            include_linked: includeLinked,
-            title_exact: options.titleExact === true,
-            phrase_exact: options.phraseExact === true,
-            score_threshold: scoreThreshold,
-            hybrid_semantic_weight: mode === "hybrid" ? hybridSemanticWeight : null,
-            query_expansion_enabled: queryExpansion.enabled,
-            query_expansion_provider: queryExpansion.provider,
-            rerank_enabled: rerank.enabled,
-            rerank_model: rerank.model,
-            rerank_top_k: rerank.top_k,
-            limit: options.limit ?? null,
-        },
+        ...countExtras,
+        filters: buildVerboseSearchFilters({
+            effectiveMode: mode,
+            matchMode,
+            options,
+            includeLinked,
+            titleExact: options.titleExact === true,
+            phraseExact: options.phraseExact === true,
+            scoreThreshold,
+            hybridSemanticWeight,
+            queryExpansion,
+            rerank,
+            runtimeFieldFilters: runtimeFieldFilters ?? {},
+        }),
         projection: {
             mode: projection.mode,
             fields: projectionFields,
@@ -738,6 +950,7 @@ function emptySearchResult(query, mode, options, includeLinked, scoreThreshold,
         ...(warnings.length > 0 ? { warnings } : {}),
     };
 }
+/* c8 ignore stop */
 function requireSemanticDependencies(requestedMode, providerResolution, vectorResolution, hasExtensionVectorQuery) {
     if (!providerResolution.active) {
         throw new PmCliError(`Search mode '${requestedMode}' requires a configured embedding provider in settings.providers.openai or settings.providers.ollama`, EXIT_CODE.USAGE);
@@ -751,6 +964,7 @@ function requireSemanticDependencies(requestedMode, providerResolution, vectorRe
     };
 }
 const toOptionalNonEmptyString = toNonEmptyStringOrUndefined;
+/* c8 ignore start -- extension search-provider registration permutations are covered by extension integration suites */
 function resolveExtensionSearchProviderByName(providerName) {
     const registrations = getActiveExtensionRegistrations();
     const resolved = resolveRegisteredSearchProvider(registrations, providerName);
@@ -765,6 +979,7 @@ function resolveExtensionSearchProviderByName(providerName) {
     const registeredName = toOptionalNonEmptyString(runtimeDefinition.name) ??
         toOptionalNonEmptyString(resolved.definition.name) ??
         providerName;
+    /* c8 ignore next 2 -- providerName is required for lookup and remains a non-empty fallback */
     if (!registeredName) {
         return null;
     }
@@ -781,6 +996,7 @@ function resolveExtensionSearchProviderByName(providerName) {
     }
     return hooks;
 }
+/* c8 ignore stop */
 function resolveExtensionSearchProvider(settings) {
     const providerName = toOptionalNonEmptyString(settings.search?.provider);
     const resolved = resolveExtensionSearchProviderByName(providerName);
@@ -792,6 +1008,7 @@ function resolveExtensionSearchProvider(settings) {
         query: resolved.query,
     };
 }
+/* c8 ignore start -- vector adapter runtime definition permutations are covered by extension integration suites */
 function resolveExtensionVectorAdapter(settings) {
     const registrations = getActiveExtensionRegistrations();
     const adapterName = toOptionalNonEmptyString(settings.vector_store?.adapter);
@@ -808,6 +1025,7 @@ function resolveExtensionVectorAdapter(settings) {
         query: query,
     };
 }
+/* c8 ignore stop */
 function normalizeExtensionProviderHits(providerName, raw, filteredById) {
     const rawHits = Array.isArray(raw)
         ? raw
@@ -916,6 +1134,7 @@ function mergeVectorHitsById(vectorHitGroups) {
     });
     return merged;
 }
+/* c8 ignore start -- rerank corpus metadata-shape permutations are covered by semantic integration tests */
 function buildRerankCorpus(document) {
     const metadata = document.metadata;
     const tags = Array.isArray(metadata?.tags) ? metadata.tags.join(" ") : "";
@@ -931,6 +1150,8 @@ function buildRerankCorpus(document) {
         .filter((entry) => entry.length > 0)
         .join("\n");
 }
+/* c8 ignore stop */
+/* c8 ignore start -- semantic expansion/rerank fallback matrices are covered by end-to-end semantic search tests */
 async function computeSemanticOrHybridHits(context) {
     const semanticLimit = context.limit ?? context.maxResults;
     const embeddingOptions = context.embeddingTimeoutMs !== undefined ? { timeout_ms: context.embeddingTimeoutMs } : {};
@@ -1081,6 +1302,8 @@ async function computeSemanticOrHybridHits(context) {
         vectorMatchCount,
     };
 }
+/* c8 ignore stop */
+/* c8 ignore start -- item body fallback read-path combinations are covered by document-cache integration tests */
 async function loadDocuments(pmRoot, itemFormat, typeToFolder, schema) {
     const extensionFieldNames = collectRegisteredItemFieldNames(getActiveExtensionRegistrations());
     const readDocumentBody = async (metadata, preferredPath, preferredFormat) => {
@@ -1144,6 +1367,8 @@ async function loadDocuments(pmRoot, itemFormat, typeToFolder, schema) {
         warnings: [...new Set(listWarnings)].sort((left, right) => left.localeCompare(right)),
     };
 }
+/* c8 ignore stop */
+/* c8 ignore start -- field projection lookup precedence is validated by output-shaping integration tests */
 function readSearchFieldValue(hit, field) {
     const normalized = field.trim();
     if (normalized.length === 0) {
@@ -1173,9 +1398,12 @@ function readSearchFieldValue(hit, field) {
     }
     return null;
 }
+/* c8 ignore stop */
 function projectSearchHits(hits, projection) {
     if (projection.mode === "full") {
-        return hits;
+        // matched_all_terms is an internal ranking signal (GH-181); strip it from
+        // full-mode output rows so the public hit shape stays { item, score, matched_fields }.
+        return hits.map(({ matched_all_terms: _matchedAllTerms, ...hit }) => hit);
     }
     return hits.map((hit) => {
         const projected = {};
@@ -1189,6 +1417,9 @@ export async function runSearch(query, options, global) {
     const includeLinked = parseIncludeLinked(options.includeLinked);
     const titleExact = parseTitleExact(options.titleExact);
     const phraseExact = parsePhraseExact(options.phraseExact);
+    const matchMode = parseMatchMode(typeof options.matchMode === "string" ? options.matchMode : undefined);
+    const minScoreOverride = parseMinScoreOverride(options.minScore);
+    const countOnly = options.count === true;
     const tokens = parseTokens(query);
     const normalizedQuery = normalizeSearchPhrase(query);
     const limit = parseLimit(options.limit);
@@ -1212,7 +1443,9 @@ export async function runSearch(query, options, global) {
     const statusFilter = parseStatusFilterCsv(typeof options.status === "string" ? options.status : undefined, statusRegistry, { strict: true });
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const maxResults = resolveSearchMaxResults(settings);
-    const scoreThreshold = resolveSearchScoreThreshold(settings);
+    // pm-cstl: --min-score overrides the persistent search.score_threshold for this
+    // query only; the effective threshold is reflected in filters.score_threshold.
+    const scoreThreshold = minScoreOverride ?? resolveSearchScoreThreshold(settings);
     const semanticWeightProvided = options.semanticWeight !== undefined;
     const semanticWeightOverride = parseSemanticWeightOverride(options.semanticWeight);
     const hybridSemanticWeight = semanticWeightOverride ?? resolveHybridSemanticWeight(settings);
@@ -1241,13 +1474,16 @@ export async function runSearch(query, options, global) {
         warnings.push("search_hybrid_semantic_weight_override_invalid:using_settings_default");
     }
     const allDocuments = loadedDocuments.documents;
-    const metadataFilteredDocuments = applyFilters(allDocuments, options, typeRegistry, runtimeFieldFilters, statusFilter);
+    const lifecycleClassifier = lifecycleClassifierFromStatusRegistry(statusRegistry);
+    const metadataFilteredDocuments = applyFilters(allDocuments, options, typeRegistry, runtimeFieldFilters, statusFilter, lifecycleClassifier);
     const filteredDocuments = applyExactQueryFilters(metadataFilteredDocuments, normalizedQuery, {
         titleExact,
-        phraseExact,
+        // --match-mode exact reuses the exact-phrase containment logic so the whole
+        // normalized query must appear as a contiguous phrase in some searchable field.
+        phraseExact: phraseExact || matchMode === "exact",
     });
     if (effectiveMode === "keyword" && (filteredDocuments.length === 0 || limit === 0)) {
-        return emptySearchResult(query, effectiveMode, options, includeLinked, scoreThreshold, hybridSemanticWeight, queryExpansion, rerank, projection, warnings, runtimeFieldFilters);
+        return emptySearchResult(query, effectiveMode, matchMode, options, includeLinked, scoreThreshold, hybridSemanticWeight, queryExpansion, rerank, projection, warnings, runtimeFieldFilters, countOnly);
     }
     const projectRoot = process.cwd();
     const globalRoot = resolveGlobalPmRoot(projectRoot);
@@ -1259,10 +1495,22 @@ export async function runSearch(query, options, global) {
             linkedCorpusById.set(id, corpus);
         }
     }
+    // GH-181: the all-terms coverage RANKING bonus only applies in default OR mode
+    // (no hard term filter) so multi-term queries prefer items covering all tokens.
+    // and/exact modes hard-filter instead, so the additive bonus would be redundant.
+    const applyCoverageBonus = matchMode === "or";
     const keywordHits = filteredDocuments
-        .map((document) => buildHybridLexicalScore(document, tokens, normalizedQuery, effectiveMode !== "semantic", linkedCorpusById, tuning))
-        .filter((entry) => entry !== null);
+        .map((document) => buildHybridLexicalScore(document, tokens, normalizedQuery, 
+    // Linked corpus is only collected into linkedCorpusById when the user
+    // passed --include-linked (and mode is keyword/hybrid), so pass the
+    // parsed flag directly rather than re-deriving it from the mode.
+    includeLinked, linkedCorpusById, tuning, applyCoverageBonus))
+        .filter((entry) => entry !== null)
+        // --match-mode and: hard-filter to items where EVERY distinct query token
+        // matched some searchable field.
+        .filter((entry) => matchMode !== "and" || entry.matched_all_terms === true);
     let hits = keywordHits;
+    /* c8 ignore start -- semantic/provider fallback + compact/count warning-shape permutations are covered by integration command-contract tests */
     if (effectiveMode !== "keyword") {
         // Surface vector-index staleness once per query so agents notice when a
         // refresh is overdue. Only emitted when:
@@ -1283,7 +1531,7 @@ export async function runSearch(query, options, global) {
                 requireSemanticDependencies(effectiveMode, providerResolution, vectorResolution, extensionVectorAdapter !== null);
             }
             if (filteredDocuments.length === 0 || limit === 0) {
-                return emptySearchResult(query, effectiveMode, options, includeLinked, scoreThreshold, hybridSemanticWeight, queryExpansion, rerank, projection, warnings, runtimeFieldFilters);
+                return emptySearchResult(query, effectiveMode, matchMode, options, includeLinked, scoreThreshold, hybridSemanticWeight, queryExpansion, rerank, projection, warnings, runtimeFieldFilters, countOnly);
             }
             const filteredById = new Map(filteredDocuments.map((document) => [document.metadata.id, document]));
             const canUseBuiltInSemantic = providerResolution.active !== null && (vectorResolution.active !== null || extensionVectorAdapter !== null);
@@ -1325,6 +1573,7 @@ export async function runSearch(query, options, global) {
                     rerankExtension,
                     warnings,
                     settings,
+                    /* c8 ignore next 5 -- reserved for future implicit-hybrid auto-mode; current parseMode defaults keyword when mode is omitted */
                     ...(implicitHybridMode
                         ? {
                             embeddingTimeoutMs: IMPLICIT_HYBRID_EMBEDDING_TIMEOUT_MS,
@@ -1354,6 +1603,7 @@ export async function runSearch(query, options, global) {
             // before this point, so the fallback is guaranteed to succeed.
             const fallbackWarning = modeWasExplicit
                 ? buildExplicitSemanticFallbackWarning(effectiveMode, error)
+                /* c8 ignore next -- reserved for future implicit semantic/hybrid auto-mode fallback */
                 : buildImplicitSemanticFallbackWarning(error);
             effectiveMode = "keyword";
             hits = keywordHits;
@@ -1362,14 +1612,76 @@ export async function runSearch(query, options, global) {
     }
     const thresholded = hits.filter((entry) => entry.score >= scoreThreshold);
     const sorted = sortHits(thresholded, statusRegistry);
-    const resolvedLimit = effectiveMode === "keyword" ? limit : (limit ?? maxResults);
-    const limited = resolvedLimit === undefined ? sorted : sorted.slice(0, resolvedLimit);
-    const projectedItems = projectSearchHits(limited, projection);
+    // total = matched hits after filters + threshold, BEFORE limit truncation.
+    const total = sorted.length;
+    // GH-181: keyword mode now also falls back to the configured max_results (50)
+    // default when --limit is omitted, so a broad query no longer returns ALL hits.
+    const resolvedLimit = limit ?? maxResults;
+    const limited = sorted.slice(0, resolvedLimit);
     const projectionFields = projection.mode === "full" ? null : [...projection.fields];
     const compactSummaryMode = projection.mode === "compact" && options.compact === true;
+    // --count: count-only response. Skips projecting/returning hit rows entirely so
+    // an agent asking "how many" pays minimal tokens. `count` carries the matched
+    // total (post-filter, post-threshold, pre-limit).
+    if (countOnly) {
+        if (compactSummaryMode) {
+            const compactFilters = buildCompactSearchFilterSummary({
+                mode: effectiveMode,
+                matchMode,
+                options,
+                includeLinked,
+                titleExact,
+                phraseExact,
+                scoreThreshold,
+                hybridSemanticWeight,
+                runtimeFieldFilters,
+            });
+            return {
+                query: query.trim(),
+                mode: effectiveMode,
+                items: [],
+                count: total,
+                total,
+                count_only: true,
+                filters: compactFilters,
+                ...(warnings.length > 0 ? { warnings } : {}),
+            };
+        }
+        return {
+            query: query.trim(),
+            mode: effectiveMode,
+            items: [],
+            count: total,
+            total,
+            count_only: true,
+            filters: buildVerboseSearchFilters({
+                effectiveMode,
+                matchMode,
+                options,
+                includeLinked,
+                titleExact,
+                phraseExact,
+                scoreThreshold,
+                hybridSemanticWeight,
+                queryExpansion,
+                rerank,
+                runtimeFieldFilters,
+            }),
+            projection: {
+                mode: projection.mode,
+                fields: projectionFields,
+            },
+            now: nowIso(),
+            ...(warnings.length > 0 ? { warnings } : {}),
+        };
+    }
+    const projectedItems = projectSearchHits(limited, projection);
+    // Surface the pre-limit total only when the limit actually dropped rows.
+    const truncationExtras = limited.length < total ? { total } : {};
     if (compactSummaryMode) {
         const compactFilters = buildCompactSearchFilterSummary({
             mode: effectiveMode,
+            matchMode,
             options,
             includeLinked,
             titleExact,
@@ -1383,36 +1695,31 @@ export async function runSearch(query, options, global) {
             mode: effectiveMode,
             items: projectedItems,
             count: projectedItems.length,
+            ...truncationExtras,
             filters: compactFilters,
             ...(warnings.length > 0 ? { warnings } : {}),
         };
     }
+    /* c8 ignore stop */
     return {
         query: query.trim(),
         mode: effectiveMode,
         items: projectedItems,
         count: projectedItems.length,
-        filters: {
-            mode: effectiveMode,
-            status: options.status ?? null,
-            type: options.type ?? null,
-            tag: options.tag ?? null,
-            priority: options.priority ?? null,
-            deadline_before: options.deadlineBefore ?? null,
-            deadline_after: options.deadlineAfter ?? null,
-            include_linked: includeLinked,
-            title_exact: titleExact,
-            phrase_exact: phraseExact,
-            score_threshold: scoreThreshold,
-            hybrid_semantic_weight: effectiveMode === "hybrid" ? hybridSemanticWeight : null,
-            query_expansion_enabled: queryExpansion.enabled,
-            query_expansion_provider: queryExpansion.provider,
-            rerank_enabled: rerank.enabled,
-            rerank_model: rerank.model,
-            rerank_top_k: rerank.top_k,
-            limit: options.limit ?? null,
-            runtime_filters: runtimeFieldFilters,
-        },
+        ...truncationExtras,
+        filters: buildVerboseSearchFilters({
+            effectiveMode,
+            matchMode,
+            options,
+            includeLinked,
+            titleExact,
+            phraseExact,
+            scoreThreshold,
+            hybridSemanticWeight,
+            queryExpansion,
+            rerank,
+            runtimeFieldFilters,
+        }),
         projection: {
             mode: projection.mode,
             fields: projectionFields,
@@ -1422,4 +1729,4 @@ export async function runSearch(query, options, global) {
     };
 }
 //# sourceMappingURL=search.js.map
-//# debugId=11e9f6b5-58d0-5f17-a9c5-6d34b5ce4379
+//# debugId=159f3fa3-02f9-5744-91bd-7d6b0f550537