@shrkcrft/inspector 0.1.0-alpha.30 → 0.1.0-alpha.31

package/dist/query-intent.js

@@ -0,0 +1,336 @@
+/**
+ * THE query-intent classifier.
+ *
+ * One answer to "what shape of work does this query ask for?". It replaces
+ * three parallel create/planning detectors (the inspector's
+ * `looksLikeScaffolding`, the CLI's `looksLikeCreateBuild` /
+ * `looksLikePlanning`) and is consulted by change-intent and
+ * prepare-agent-task instead of their own verb regexes. Deterministic; terms
+ * come from THE term normaliser (`match-terms.ts`).
+ *
+ * Create rules — the ones the recommender's source-writing gate hangs on:
+ *   - a create verb in slot 0 is STRONG, unless the next term shows it is a
+ *     subject noun ("build is broken", "build fails");
+ *   - a create verb in slots 1–3 right after a lead-in ("please add",
+ *     "I want to generate", "we should add") is STRONG;
+ *   - any other create verb in slots 1–3 is LOOSE, and a repair/diagnosis
+ *     marker anywhere in the query VETOES it ("fix the broken build",
+ *     "why does the new route fail");
+ *   - `new` is never strong on its own — it is an adjective as often as a verb.
+ * A strong create survives a marker ("add a fix for the crash" is create work).
+ */
+import { normaliseTerms } from "./match-terms.js";
+import { QueryIntent } from "./query-intent-kind.js";
+/** Only the first four terms carry the query's verb ("help me plan …"). */
+const SLOT_WINDOW = 4;
+const CREATE_VERBS = new Set([
+    'create',
+    'build',
+    'add',
+    'generate',
+    'scaffold',
+    'implement',
+    'make',
+    'new',
+    'introduce',
+    'write',
+]);
+/** Create words that are never a strong create signal on their own. */
+const WEAK_CREATE_WORDS = new Set(['new']);
+/** A create verb right after one of these is an imperative ("please add", "want to generate"). */
+const CREATE_LEAD_INS = new Set([
+    'please',
+    'to',
+    'i',
+    'we',
+    'lets',
+    'let',
+    'want',
+    'need',
+    'can',
+    'should',
+    'must',
+    'will',
+    'me',
+    'us',
+    'just',
+    'also',
+]);
+/** After a slot-0 create word, these show it is the subject noun, not a verb. */
+const NOUN_FOLLOWERS = new Set([
+    'is',
+    'are',
+    'was',
+    'were',
+    'has',
+    'have',
+    'had',
+    'keeps',
+    'kept',
+    'broke',
+    'breaks',
+    'broken',
+    'fails',
+    'failed',
+    'failing',
+    'crashes',
+    'crashed',
+    'doesnt',
+    'didnt',
+    'cannot',
+    'cant',
+    'wont',
+    'isnt',
+    'wasnt',
+    'error',
+    'errors',
+    'hangs',
+    'stopped',
+    'stops',
+]);
+const REPAIR_MARKERS = new Set(['fix', 'fixes', 'fixing', 'repair', 'resolve', 'unbreak', 'restore']);
+const DIAGNOSE_MARKERS = new Set([
+    'broken',
+    'fail',
+    'fails',
+    'failing',
+    'failed',
+    'failure',
+    'failures',
+    'error',
+    'errors',
+    'crash',
+    'crashes',
+    'crashed',
+    'crashing',
+    'bug',
+    'bugs',
+    'buggy',
+    'why',
+    'debug',
+    'diagnose',
+    'investigate',
+    'violation',
+    'violations',
+    'regression',
+    'regressions',
+    'doesnt',
+    'didnt',
+    'cannot',
+    'cant',
+    'wont',
+    'isnt',
+    'flaky',
+    'hang',
+    'hangs',
+    'wrong',
+]);
+/** Markers that, followed by one of {@link MARKER_COMPOUND_NOUNS}, name a THING ("error handling"). */
+const COMPOUNDABLE_MARKERS = new Set(['error', 'errors', 'bug', 'bugs', 'crash', 'failure']);
+const MARKER_COMPOUND_NOUNS = new Set([
+    'handling',
+    'handler',
+    'handlers',
+    'message',
+    'messages',
+    'page',
+    'pages',
+    'boundary',
+    'boundaries',
+    'type',
+    'types',
+    'code',
+    'codes',
+    'class',
+    'classes',
+    'report',
+    'reports',
+    'reporting',
+    'tracker',
+    'tracking',
+    'state',
+    'states',
+]);
+/** The planning verbs (moved from the CLI's DX#2 classifier, unchanged). */
+const PLANNING_VERBS = new Set([
+    'plan',
+    'design',
+    'propose',
+    'review',
+    'audit',
+    'analyze',
+    'analyse',
+    'explore',
+    'consider',
+    'investigate',
+    'survey',
+    'compare',
+    'evaluate',
+    'assess',
+]);
+const REVIEW_VERBS = new Set(['review', 'audit']);
+/** "review" + one of these reviews a CHANGE (a PR), not a design. */
+const REVIEW_OBJECTS = new Set([
+    'pr',
+    'prs',
+    'pull',
+    'diff',
+    'diffs',
+    'change',
+    'changes',
+    'changeset',
+    'branch',
+    'commit',
+    'commits',
+    'patch',
+    'mr',
+]);
+const REFACTOR_VERBS = new Set([
+    'refactor',
+    'refactoring',
+    'rename',
+    'extract',
+    'cleanup',
+    'clean',
+    'tidy',
+    'simplify',
+    'restructure',
+    'reorganize',
+    'reorganise',
+    'move',
+    'split',
+    'consolidate',
+    'dedupe',
+    'deduplicate',
+    'rewrite',
+    'inline',
+    'decouple',
+]);
+const RELEASE_VERBS = new Set(['release', 'publish', 'ship', 'tag', 'bump', 'version', 'deploy']);
+const EXPLAIN_LEADS = new Set([
+    'explain',
+    'what',
+    'how',
+    'where',
+    'which',
+    'who',
+    'describe',
+    'show',
+    'understand',
+    'trace',
+    'list',
+    'find',
+]);
+/** "let's" → "lets", "doesn't" → "doesnt": one term, so the marker/lead-in sets can name it. */
+function expandContractions(query) {
+    return query.replace(/\b(let|don|doesn|didn|can|won|isn|wasn|aren)['’](s|t)\b/gi, '$1$2');
+}
+/** "error handling", "bug report": the marker word names a thing, not a failure. */
+function isCompound(terms, i) {
+    const next = terms[i + 1];
+    return COMPOUNDABLE_MARKERS.has(terms[i]) && next !== undefined && MARKER_COMPOUND_NOUNS.has(next);
+}
+function isMarker(terms, i) {
+    const t = terms[i];
+    if (!REPAIR_MARKERS.has(t) && !DIAGNOSE_MARKERS.has(t))
+        return false;
+    return !isCompound(terms, i);
+}
+function firstIn(terms, set, window = terms.length) {
+    const n = Math.min(window, terms.length);
+    for (let i = 0; i < n; i++)
+        if (set.has(terms[i]))
+            return i;
+    return -1;
+}
+/** The best create sighting in the slot window: a strong one beats a loose one; earliest among equals. */
+function findCreate(terms) {
+    let loose;
+    const n = Math.min(SLOT_WINDOW, terms.length);
+    for (let i = 0; i < n; i++) {
+        const t = terms[i];
+        if (!CREATE_VERBS.has(t))
+            continue;
+        let strong = false;
+        if (!WEAK_CREATE_WORDS.has(t)) {
+            if (i === 0) {
+                // "build is broken" / "build error in billing": the create word is the
+                // subject noun. "add error handling" is not — `error handling` is a thing.
+                const next = terms[1];
+                if (next !== undefined && NOUN_FOLLOWERS.has(next) && !isCompound(terms, 1))
+                    continue;
+                strong = true;
+            }
+            else if (CREATE_LEAD_INS.has(terms[i - 1])) {
+                strong = true;
+            }
+        }
+        if (strong)
+            return { index: i, verb: t, strong: true };
+        if (!loose)
+            loose = { index: i, verb: t, strong: false };
+    }
+    return loose;
+}
+/**
+ * THE eligibility rule for SOURCE-WRITING offers — a scaffold, a `gen` /
+ * `apply` command, a suggested generation: only a create/build query admits
+ * them. The recommender gates its writes-source candidates on it and the task
+ * packet gates its suggested generation on it, so the two cannot disagree
+ * about one query (spec 2.3, round 11 review R11-GAP-6).
+ */
+export function intentAdmitsSourceWrites(intent) {
+    return intent.intent === QueryIntent.Create;
+}
+/**
+ * A diagnose / repair query ("fix the broken build", "why does the new route
+ * fail"): a create/scaffold pipeline, a template, or a source-writing command
+ * is never an answer to it — the task packet drops them.
+ */
+export function intentIsRepairOrDiagnosis(intent) {
+    return intent.intent === QueryIntent.Repair || intent.intent === QueryIntent.Diagnose;
+}
+/** Classify a free-text query. Pure and deterministic. */
+export function classifyQueryIntent(query) {
+    const terms = normaliseTerms(expandContractions(query));
+    if (terms.length === 0)
+        return { intent: QueryIntent.Unknown, terms };
+    let marker;
+    let repair = false;
+    for (let i = 0; i < terms.length; i++) {
+        if (!isMarker(terms, i))
+            continue;
+        marker ??= terms[i];
+        if (REPAIR_MARKERS.has(terms[i]))
+            repair = true;
+    }
+    const create = findCreate(terms);
+    const createDetected = create !== undefined && (create.strong || marker === undefined);
+    const planIndex = firstIn(terms, PLANNING_VERBS, SLOT_WINDOW);
+    const planVerb = planIndex >= 0 ? terms[planIndex] : undefined;
+    const base = {
+        terms,
+        ...(createDetected ? { createVerb: create.verb } : {}),
+        ...(planVerb !== undefined ? { planVerb } : {}),
+        ...(create !== undefined && !createDetected && marker !== undefined ? { vetoedBy: marker } : {}),
+    };
+    if (createDetected && !(planIndex >= 0 && planIndex < create.index)) {
+        return { intent: QueryIntent.Create, ...base };
+    }
+    if (repair)
+        return { intent: QueryIntent.Repair, ...base };
+    if (marker !== undefined)
+        return { intent: QueryIntent.Diagnose, ...base };
+    if (firstIn(terms, REVIEW_VERBS, SLOT_WINDOW) >= 0 && firstIn(terms, REVIEW_OBJECTS) >= 0) {
+        return { intent: QueryIntent.Review, ...base };
+    }
+    if (planVerb !== undefined)
+        return { intent: QueryIntent.Plan, ...base };
+    if (firstIn(terms, REFACTOR_VERBS, SLOT_WINDOW) >= 0)
+        return { intent: QueryIntent.Refactor, ...base };
+    if (firstIn(terms, RELEASE_VERBS, SLOT_WINDOW) >= 0)
+        return { intent: QueryIntent.Release, ...base };
+    if (EXPLAIN_LEADS.has(terms[0]))
+        return { intent: QueryIntent.Explain, ...base };
+    return { intent: QueryIntent.Unknown, ...base };
+}

package/dist/query-resolver.d.ts

@@ -27,12 +27,30 @@ export interface IQueryResolution {
     bestMatch?: IQueryMatch;
     alternatives: ReadonlyArray<IQueryMatch>;
     confidence: 'exact' | 'high' | 'medium' | 'low' | 'unknown';
+    /**
+     * Match kinds that were NOT searched because their inventory lives above
+     * this layer and was not supplied (today: `command`, without
+     * {@link IQueryResolveOptions.commands}). A query that "matched nothing"
+     * there was never compared — not the same as no match.
+     */
+    unconsulted?: ReadonlyArray<QueryMatchKind>;
 }
 export interface IQueryResolveOptions {
     /** Limit number of alternatives returned. */
     limit?: number;
     /** Restrict to a subset of match kinds. */
     kinds?: ReadonlyArray<QueryMatchKind>;
+    /**
+     * The command inventory to rank `command` matches against — injected by the
+     * CLI from its command index (the inventory lives above this layer). It used
+     * to be read off `inspection.commandCatalog`, a property no inspection ever
+     * has, so command matching silently ranked nothing.
+     */
+    commands?: ReadonlyArray<{
+        id: string;
+        name?: string;
+        description?: string;
+    }>;
 }
 export declare function resolveQuery(inspection: ISharkcraftInspection, query: string, options?: IQueryResolveOptions): IQueryResolution;
 //# sourceMappingURL=query-resolver.d.ts.map

package/dist/query-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-resolver.d.ts","sourceRoot":"","sources":["../src/query-resolver.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAMvE,eAAO,MAAM,uBAAuB,mCAAmC,CAAC;AAExE,oBAAY,cAAc;IACxB,IAAI,SAAS;IACb,SAAS,cAAc;IACvB,SAAS,cAAc;IACvB,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,SAAS,eAAe;IACxB,UAAU,gBAAgB;IAC1B,OAAO,aAAa;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,cAAc,CAAC;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,uBAAuB,CAAC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,YAAY,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IACzC,UAAU,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;CAC7D;AAED,MAAM,WAAW,oBAAoB;IACnC,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,KAAK,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;CACvC;AAqID,wBAAgB,YAAY,CAC1B,UAAU,EAAE,qBAAqB,EACjC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,oBAAyB,GACjC,gBAAgB,CA8BlB"}
+{"version":3,"file":"query-resolver.d.ts","sourceRoot":"","sources":["../src/query-resolver.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAMvE,eAAO,MAAM,uBAAuB,mCAAmC,CAAC;AAExE,oBAAY,cAAc;IACxB,IAAI,SAAS;IACb,SAAS,cAAc;IACvB,SAAS,cAAc;IACvB,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,SAAS,eAAe;IACxB,UAAU,gBAAgB;IAC1B,OAAO,aAAa;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,cAAc,CAAC;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,uBAAuB,CAAC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,YAAY,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IACzC,UAAU,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;IAC5D;;;;;OAKG;IACH,WAAW,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,oBAAoB;IACnC,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,KAAK,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/E;AAuID,wBAAgB,YAAY,CAC1B,UAAU,EAAE,qBAAqB,EACjC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,oBAAyB,GACjC,gBAAgB,CAmClB"}

package/dist/query-resolver.js

@@ -125,9 +125,8 @@ function rankPlaybooks(inspection, query) {
 function rankPolicies(inspection, query) {
     return rankList(listPolicyIds(inspection).map((id) => ({ id })), query, QueryMatchKind.Policy);
 }
-function rankCommands(inspection, query) {
-    const cat = inspection.commandCatalog ?? [];
-    return rankList(cat, query, QueryMatchKind.Command);
+function rankCommands(commands, query) {
+    return rankList(commands ?? [], query, QueryMatchKind.Command);
 }
 function pickConfidence(top) {
     if (!top)
@@ -146,18 +145,22 @@ export function resolveQuery(inspection, query, options = {}) {
     const file = fileMatches(query, inspection.projectRoot);
     if (file)
         matches.push(file);
-    matches.push(...rankConstructs(inspection, query), ...rankKnowledge(inspection, query), ...rankTemplates(inspection, query), ...rankHelpers(query), ...rankPlaybooks(inspection, query), ...rankPolicies(inspection, query), ...rankCommands(inspection, query));
+    matches.push(...rankConstructs(inspection, query), ...rankKnowledge(inspection, query), ...rankTemplates(inspection, query), ...rankHelpers(query), ...rankPlaybooks(inspection, query), ...rankPolicies(inspection, query), ...rankCommands(options.commands, query));
     const filtered = options.kinds && options.kinds.length > 0
         ? matches.filter((m) => options.kinds.includes(m.kind))
         : matches;
     filtered.sort((a, b) => b.score - a.score);
     const limit = options.limit ?? 10;
     const top = filtered[0];
+    const commandsWanted = !options.kinds || options.kinds.length === 0 || options.kinds.includes(QueryMatchKind.Command);
     return {
         schema: QUERY_RESOLUTION_SCHEMA,
         query,
         ...(top ? { bestMatch: top } : {}),
         alternatives: filtered.slice(1, limit + 1),
         confidence: pickConfidence(top),
+        ...(commandsWanted && options.commands === undefined
+            ? { unconsulted: [QueryMatchKind.Command] }
+            : {}),
     };
 }

package/dist/ranked-recommendations.d.ts

@@ -0,0 +1,36 @@
+import type { IQueryIntentResult } from './query-intent-result.js';
+import type { IRecommendationCandidate } from './recommendation-candidate.js';
+import type { IRecommendationConfidence } from './recommendation-confidence.js';
+import type { ITaskRoutingMatchResult } from './task-routing-hint-registry.js';
+/**
+ * THE ranked recommendation list. The recommend headline, `nextCommand`,
+ * confidence and reasons, the CLI, MCP `recommend_commands` and
+ * `shrk context` all derive from this one value.
+ */
+export interface IRankedRecommendations {
+    readonly query: string;
+    readonly intent: IQueryIntentResult;
+    /** The floor multiplier in effect (CLI `--min-score` > MCP `minScore` > config `recommend.minScore` > 1). */
+    readonly floor: number;
+    /** Every candidate: the recommendations first (ranked), then the suppressed rows. */
+    readonly candidates: readonly IRecommendationCandidate[];
+    /** Eligible rows, deduped by command, ranked (a planning row is pinned first). */
+    readonly recommendations: readonly IRecommendationCandidate[];
+    readonly confidence: IRecommendationConfidence;
+    /** Computed LAST, over `recommendations`: never a writes-source guess. */
+    readonly nextCommand: string;
+    /** The routing-hint matches the list was built from (`explainTaskRouting`). */
+    readonly routingMatches: readonly ITaskRoutingMatchResult[];
+    /** The shared ranker's raw top template / pipeline (null when the ranker did not run). */
+    readonly rankerTop: {
+        readonly topTemplate: {
+            readonly id: string;
+            readonly score: number;
+        } | null;
+        readonly topPipeline: {
+            readonly id: string;
+            readonly score: number;
+        } | null;
+    } | null;
+}
+//# sourceMappingURL=ranked-recommendations.d.ts.map

package/dist/ranked-recommendations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ranked-recommendations.d.ts","sourceRoot":"","sources":["../src/ranked-recommendations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAC9E,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAChF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAE/E;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,6GAA6G;IAC7G,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qFAAqF;IACrF,QAAQ,CAAC,UAAU,EAAE,SAAS,wBAAwB,EAAE,CAAC;IACzD,kFAAkF;IAClF,QAAQ,CAAC,eAAe,EAAE,SAAS,wBAAwB,EAAE,CAAC;IAC9D,QAAQ,CAAC,UAAU,EAAE,yBAAyB,CAAC;IAC/C,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAC5D,0FAA0F;IAC1F,QAAQ,CAAC,SAAS,EAAE;QAClB,QAAQ,CAAC,WAAW,EAAE;YAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAC;QAC7E,QAAQ,CAAC,WAAW,EAAE;YAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAC;KAC9E,GAAG,IAAI,CAAC;CACV"}

package/dist/ranked-recommendations.js

@@ -0,0 +1 @@
+export {};

package/dist/ranker-explainability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ranker-explainability.d.ts","sourceRoot":"","sources":["../src/ranker-explainability.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ranker-explainability.d.ts","sourceRoot":"","sources":["../src/ranker-explainability.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAUvE,eAAO,MAAM,4BAA4B,wCAAwC,CAAC;AAElF,oBAAY,iBAAiB;IAC3B,SAAS,cAAc;IACvB,QAAQ,aAAa;IACrB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,SAAS,cAAc;IACvB,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,QAAQ,aAAa;CACtB;AAED,MAAM,WAAW,qBAAqB;IACpC,sCAAsC;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,IAAI,CAAC,EAAE,iBAAiB,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,OAAO,4BAA4B,CAAC;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,qBAAqB,CAAC;IAC/B,gDAAgD;IAChD,KAAK,EAAE,OAAO,CAAC;IACf,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4FAA4F;IAC5F,QAAQ,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,cAAc,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAChD,kFAAkF;IAClF,cAAc,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAChD,qDAAqD;IACrD,WAAW,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC3C,2EAA2E;IAC3E,WAAW,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAClD,8DAA8D;IAC9D,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,oCAAoC;IACpC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,iEAAiE;IACjE,UAAU,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAC/C,6BAA6B;IAC7B,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAgTD,MAAM,WAAW,qBAAqB;IACpC,yCAAyC;IACzC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,qBAAqB,EACjC,OAAO,EAAE,qBAAqB,EAC9B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAmHtB;AAID,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,oBAAoB,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CA+D7F;AAMD,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,oBAAoB,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CA4DjG;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,oBAAoB,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAS7F"}

package/dist/ranker-explainability.js

@@ -1,6 +1,8 @@
 import { buildSearchIndex, searchIndex, } from "./search-index.js";
 import { listSearchTuning, tuningBoostFor, } from "./search-tuning-registry.js";
 import { rankAll } from "./task-ranker.js";
+import { isSearchDocumentPrefix, parseSearchDocumentId, searchDocumentId, searchDocumentPrefixForKind, searchKindForPrefix, } from "./search-document-id.js";
+import { tuningQueryTokens } from "./tuning-query-tokens.js";
 export const RANKER_EXPLAINABILITY_SCHEMA = 'sharkcraft.ranker-explainability/v1';
 export var RankerExplainKind;
 (function (RankerExplainKind) {
@@ -186,13 +188,13 @@ function inferDomainAppliesWhen(taskLower) {
 function commonSuggestedCommands(found, hit) {
     if (!found) {
         return [
-            'shrk commands suggest "<partial id>"',
-            'shrk find <text>',
+            'shrk commands search "<partial id>"',
+            'shrk search <text>',
             'shrk search <text> --explain',
         ];
     }
     const out = [];
-    out.push(`shrk why-not ${hit?.id ?? '<id>'} --for-task "<task>"`);
+    out.push('shrk task "<task>" --explain-ranking');
     out.push('shrk search "<task>" --explain');
     out.push('shrk search tuning explain "<task>"');
     out.push('shrk coverage scaffolds --task "<task>"');
@@ -244,12 +246,34 @@ function deriveMatchedAndMissing(hit, taskOrQuery) {
         missing.push({ signal: 'appliesWhen', matched: false });
     return { matched, missing };
 }
+/**
+ * A registry hit's SEARCH-DOCUMENT id — what `tuningBoostFor` and the search
+ * index key by — from THE codec. `why` used to hand the matcher the BARE id, so
+ * it reported a dead bare boost as applied and hid every live prefixed one.
+ */
+function registryHitDocumentId(hit) {
+    const prefix = searchDocumentPrefixForKind(hit.kind);
+    return prefix ? searchDocumentId(prefix, hit.id) : hit.id;
+}
+/** The hit for a bare registry id OR its search-document id (`knowledge:foo`). */
+function findRegistryHit(hits, requested) {
+    const exact = hits.find((h) => h.id === requested);
+    if (exact)
+        return exact;
+    const parsed = parseSearchDocumentId(requested);
+    if (!parsed || !isSearchDocumentPrefix(parsed.prefix))
+        return undefined;
+    const kind = searchKindForPrefix(parsed.prefix);
+    return hits.find((h) => h.id === parsed.id && h.kind === kind);
+}
 function gatherTuningTrace(hit, tuning, taskOrQuery) {
     if (!hit)
         return [];
-    const tokens = tokenize(taskOrQuery);
+    // THE trigger tokenizer and THE document id — the same inputs the rankers
+    // hand `tuningBoostFor`, so this trace is what they apply (explain ≡ ranker).
+    const tokens = tuningQueryTokens(taskOrQuery);
     const boost = tuningBoostFor({
-        id: hit.id,
+        id: registryHitDocumentId(hit),
         kind: hit.kind,
         ...(hit.tags ? { tags: hit.tags } : {}),
         source: hit.source,
@@ -274,8 +298,12 @@ function gatherTuningTrace(hit, tuning, taskOrQuery) {
 export function explainRankerDecision(inspection, request, options = {}) {
     const topN = options.topN ?? 10;
     const hits = listRegistryHits(inspection);
-    const id = request.id;
-    const found = hits.find((h) => h.id === id);
+    // A search-document id (`knowledge:foo`) and the bare registry id (`foo`)
+    // name the same entry; the ranker compares bare ids, the search index
+    // prefixed ones.
+    const found = findRegistryHit(hits, request.id);
+    const id = found?.id ?? request.id;
+    const documentId = found ? registryHitDocumentId(found) : request.id;
     const taskOrQuery = request.task ?? request.query ?? '';
     const tuning = listSearchTuning(inspection);
     // Build search-based ranking for query mode (no task).
@@ -290,7 +318,7 @@ export function explainRankerDecision(inspection, request, options = {}) {
     if (request.query) {
         const index = buildSearchIndex(inspection);
         const result = searchIndex(index, { query: request.query, limit: Math.max(topN, 20), explain: true }, inspection);
-        const targetHit = result.hits.find((h) => h.document.id === id);
+        const targetHit = result.hits.find((h) => h.document.id === documentId);
         if (targetHit) {
             documentSnapshot = targetHit.document;
             searchScore = targetHit.score;
@@ -383,7 +411,7 @@ export function explainRankerDecision(inspection, request, options = {}) {
 // ── Rendering ───────────────────────────────────────────────────────────
 export function renderRankerExplainText(report, whyNot) {
     const lines = [];
-    const heading = whyNot ? `=== shrk why-not ${report.request.id} ===` : `=== shrk why ${report.request.id} ===`;
+    const heading = whyNot ? `=== why-not ${report.request.id} ===` : `=== why ${report.request.id} ===`;
     lines.push(heading);
     if (report.request.task)
         lines.push(`task: ${report.request.task}`);
@@ -461,7 +489,7 @@ function escHtml(s) {
 }
 export function renderRankerExplainMarkdown(report, whyNot) {
     const lines = [];
-    lines.push(`# ${whyNot ? 'shrk why-not' : 'shrk why'} \`${report.request.id}\``);
+    lines.push(`# ${whyNot ? 'why-not' : 'why'}\`${report.request.id}\``);
     if (report.request.task)
         lines.push(`Task: \`${report.request.task}\``);
     if (report.request.query)

package/dist/recommend-recipe.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A built-in recommender recipe. `terms` and `phrases` go through THE term
+ * matcher (tokens mode), so `pr` no longer fires inside "pricing" nor `pack`
+ * inside "package". `regex` is kept only for phrase-shaped alternations, every
+ * alternative anchored at a word boundary.
+ */
+export interface IRecommendRecipe {
+    readonly id: string;
+    readonly terms: readonly string[];
+    readonly phrases?: readonly string[];
+    readonly regex?: RegExp;
+    readonly recommendations: readonly {
+        readonly command: string;
+        readonly why: string;
+    }[];
+}
+//# sourceMappingURL=recommend-recipe.d.ts.map

package/dist/recommend-recipe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommend-recipe.d.ts","sourceRoot":"","sources":["../src/recommend-recipe.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,eAAe,EAAE,SAAS;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACzF"}

package/dist/recommend-recipe.js

@@ -0,0 +1 @@
+export {};

package/dist/recommend-recipes.d.ts

@@ -0,0 +1,9 @@
+import type { IRecommendRecipe } from './recommend-recipe.js';
+import type { ITermQuery } from './term-query.js';
+export declare const RECOMMEND_RECIPES: readonly IRecommendRecipe[];
+/**
+ * The evidence a recipe matched on — its matched terms and phrases, plus the
+ * regex's matched text — distinct. Empty = the recipe does not apply.
+ */
+export declare function matchRecommendRecipe(recipe: IRecommendRecipe, query: ITermQuery, text: string): string[];
+//# sourceMappingURL=recommend-recipes.d.ts.map

package/dist/recommend-recipes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommend-recipes.d.ts","sourceRoot":"","sources":["../src/recommend-recipes.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,eAAO,MAAM,iBAAiB,EAAE,SAAS,gBAAgB,EA2ExD,CAAC;AAEF;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAYxG"}