@aiwg/cli 2026.8.17 → 2026.8.19

package/dist/src/a2a/webhook.js

@@ -15,6 +15,7 @@
 //
 // @issue #1256
 import { createHmac, timingSafeEqual } from 'node:crypto';
+import { decodeStreamResponse, A2AEventReconciler } from './events.js';
 /** Header name (case-insensitive). */
 export const SIGNATURE_HEADER = 'x-aiwg-signature';
 /** Five minutes — RFC 8941 timestamp tolerance. */
@@ -111,6 +112,7 @@ function constantTimeHexEqual(a, b) {
 export class IdempotencyCache {
     capacity;
     seen = new Set();
+    pending = new Set();
     order = [];
     constructor(capacity = DEFAULT_IDEMPOTENCY_CAPACITY) {
         this.capacity = Math.max(16, capacity);
@@ -119,6 +121,23 @@ export class IdempotencyCache {
     markFresh(id) {
         if (this.seen.has(id))
             return false;
+        this.commit(id);
+        return true;
+    }
+    /** Reserve an event before parsing/routing so concurrent deliveries cannot race. */
+    begin(id) {
+        if (this.seen.has(id))
+            return 'duplicate';
+        if (this.pending.has(id))
+            return 'pending';
+        this.pending.add(id);
+        return 'fresh';
+    }
+    /** Mark a successfully routed reservation as completed. */
+    commit(id) {
+        this.pending.delete(id);
+        if (this.seen.has(id))
+            return;
         this.seen.add(id);
         this.order.push(id);
         while (this.order.length > this.capacity) {
@@ -126,7 +145,10 @@ export class IdempotencyCache {
             if (evicted !== undefined)
                 this.seen.delete(evicted);
         }
-        return true;
+    }
+    /** Release a failed reservation so a later retry can be processed. */
+    release(id) {
+        this.pending.delete(id);
     }
     size() {
         return this.seen.size;
@@ -134,15 +156,35 @@ export class IdempotencyCache {
 }
 export class PushSecretRegistry {
     entries = new Map();
+    reconcilers = new Map();
     register(entry) {
+        if (entry.protocolVersion === '1.0' && !entry.taskId) {
+            throw new Error('A2A 1.0 push config registration requires taskId ownership scope');
+        }
         this.entries.set(entry.configId, entry);
+        if (entry.taskId) {
+            this.reconcilers.set(entry.configId, new A2AEventReconciler({
+                taskId: entry.taskId,
+                ...(entry.contextId ? { contextId: entry.contextId } : {}),
+            }));
+        }
     }
     lookup(configId) {
         return this.entries.get(configId) ?? null;
     }
     unregister(configId) {
+        this.reconcilers.delete(configId);
         return this.entries.delete(configId);
     }
+    reconcile(configId, event) {
+        const entry = this.entries.get(configId);
+        const eventOwner = ownerOf(event);
+        if (entry?.taskOwner && eventOwner && entry.taskOwner !== eventOwner) {
+            throw new Error(`A2A event belongs to owner ${eventOwner}, expected ${entry.taskOwner}`);
+        }
+        const reconciler = this.reconcilers.get(configId);
+        return reconciler ? reconciler.accept(event) : event;
+    }
     /** Test/debug helper. */
     size() {
         return this.entries.size;
@@ -193,40 +235,83 @@ export async function handleWebhook(configId, body, signature, eventId, opts) {
     // Idempotency check — duplicate event-ids are accepted with 200 but
     // not re-routed. The executor's retry logic depends on a 2xx response
     // to mark delivery complete; failing here would cause infinite retry.
-    const fresh = opts.idempotency.markFresh(eventId);
-    if (!fresh) {
+    const entryForScope = opts.registry.lookup(configId);
+    const protocolVersion = entryForScope?.protocolVersion ?? '0.3';
+    const scopedEventId = [
+        configId,
+        protocolVersion,
+        entryForScope?.taskOwner ?? '',
+        entryForScope?.taskId ?? '',
+        eventId,
+    ].join('|');
+    const reservation = opts.idempotency.begin(scopedEventId);
+    if (reservation === 'duplicate') {
         return { status: 200, body: { ok: true, deduped: true } };
     }
+    if (reservation === 'pending') {
+        return {
+            status: 409,
+            body: errorBody('aiwg.webhook_event_in_progress', 'a concurrent delivery is still being processed'),
+        };
+    }
     // Route the verified payload. Errors thrown here become 500 so the
     // executor will retry — pick the abstraction carefully on the
     // mission-state side.
     const entry = opts.registry.lookup(configId);
     if (!entry) {
         // Edge case: secret was unregistered between verify and route.
+        opts.idempotency.release(scopedEventId);
         return {
             status: 404,
             body: errorBody('aiwg.webhook_secret_unknown', `configId='${configId}' no longer registered`),
         };
     }
+    if (protocolVersion === '1.0' && opts.contentType?.split(';')[0]?.trim().toLowerCase() !== 'application/a2a+json') {
+        opts.idempotency.release(scopedEventId);
+        return {
+            status: 415,
+            body: errorBody('aiwg.webhook_content_type_invalid', 'A2A 1.0 push requires application/a2a+json'),
+        };
+    }
     let parsed;
     try {
         parsed = JSON.parse(body.toString('utf8'));
     }
     catch (e) {
+        opts.idempotency.release(scopedEventId);
         return {
             status: 400,
             body: errorBody('aiwg.webhook_body_not_json', e.message),
         };
     }
+    let event;
     try {
-        await opts.route(entry, parsed);
+        event = decodeStreamResponse(protocolVersion, parsed, { eventId });
+        const accepted = opts.registry.reconcile(configId, event);
+        if (!accepted) {
+            opts.idempotency.commit(scopedEventId);
+            return { status: 200, body: { ok: true, deduped: true } };
+        }
+        event = accepted;
     }
     catch (e) {
+        opts.idempotency.release(scopedEventId);
+        return {
+            status: 400,
+            body: errorBody('aiwg.webhook_event_invalid', e.message),
+        };
+    }
+    try {
+        await opts.route(entry, event);
+    }
+    catch (e) {
+        opts.idempotency.release(scopedEventId);
         return {
             status: 500,
             body: errorBody('aiwg.webhook_route_failed', e.message),
         };
     }
+    opts.idempotency.commit(scopedEventId);
     return { status: 200, body: { ok: true } };
 }
 function errorBody(code, detail) {
@@ -237,4 +322,16 @@ function errorBody(code, detail) {
         detail,
     };
 }
+function ownerOf(event) {
+    const metadata = event.type === 'task'
+        ? event.task.metadata
+        : event.type === 'message'
+            ? event.message.metadata
+            : event.metadata;
+    const owner = metadata?.['task_owner']
+        ?? metadata?.['taskOwner']
+        ?? metadata?.['tenant_id']
+        ?? metadata?.['tenantId'];
+    return typeof owner === 'string' && owner ? owner : undefined;
+}
 //# sourceMappingURL=webhook.js.map

package/dist/src/artifacts/index-builder.js

@@ -2,7 +2,7 @@
  * Artifact Index Builder
  *
  * Scans .aiwg/ directories, extracts metadata from artifact frontmatter,
- * computes checksums, extracts @-mention dependencies, and builds a
+ * computes checksums, extracts @-mention and Markdown-link dependencies, and builds a
  * structured index at .aiwg/.index/.
  *
  * @implements #415
@@ -68,6 +68,57 @@ export function extractMentions(content) {
     }
     return Array.from(mentions);
 }
+/**
+ * Extract relative Markdown links that may resolve to graph-local artifacts.
+ *
+ * External URLs, absolute paths, and anchor-only links are intentionally absent
+ * from the accepted pattern. Resolution still happens later against indexed
+ * nodes, so a parsed link outside the active graph cannot create an edge.
+ */
+export function extractMarkdownLinks(content) {
+    const links = new Set();
+    const pattern = /(!?)\[[^\]]+\]\((\.\/?[^)#\s]+)(?:#[^)]+)?\)/g;
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+        if (match[1] === '!')
+            continue;
+        links.add(match[2]);
+    }
+    return Array.from(links);
+}
+function resolveMarkdownLinkDependency(cwd, sourcePath, rawLink, entries, graph) {
+    const target = rawLink.split('#')[0]?.trim();
+    if (!target)
+        return null;
+    const sourceFullPath = absoluteEntryPath(cwd, sourcePath, graph);
+    const targetFullPath = path.resolve(path.dirname(sourceFullPath), target);
+    let stat;
+    try {
+        stat = fs.statSync(targetFullPath);
+    }
+    catch {
+        return null;
+    }
+    if (!stat.isFile())
+        return null;
+    const indexedPath = indexPathFor(cwd, targetFullPath, graph);
+    return entries[indexedPath] ? indexedPath : null;
+}
+function addDependencyEdge(depGraph, entries, sourcePath, targetPath, type) {
+    if (sourcePath === targetPath)
+        return false;
+    if (!depGraph[sourcePath])
+        depGraph[sourcePath] = { upstream: [], downstream: [] };
+    if (!depGraph[targetPath])
+        depGraph[targetPath] = { upstream: [], downstream: [] };
+    if (depGraph[sourcePath].upstream.some(edge => edge.path === targetPath))
+        return false;
+    depGraph[sourcePath].upstream.push({ path: targetPath, type });
+    depGraph[targetPath].downstream.push({ path: sourcePath, type });
+    if (entries[targetPath])
+        entries[targetPath].dependents.push(sourcePath);
+    return true;
+}
 /**
  * Extract title from content (first # heading or frontmatter title)
  */
@@ -846,6 +897,7 @@ export async function buildIndex(cwd, options = {}) {
             const tags = flow ? flow.tags : (Array.isArray(data.tags) ? data.tags.map(String) : []);
             const summary = flow?.description ?? schemaDoc?.capability ?? runbook?.capability ?? extractSummary(data, body);
             const dependencies = extractMentions(content);
+            const markdownLinks = extractMarkdownLinks(content);
             // Discovery metadata (#1214, #1540, #1792) — meaningful for operational
             // AIWG artifact kinds. Kept undefined on document types so the index file
             // stays small for the common case.
@@ -879,6 +931,7 @@ export async function buildIndex(cwd, options = {}) {
                 checksum,
                 summary,
                 dependencies,
+                ...(markdownLinks.length > 0 ? { markdownLinks } : {}),
                 dependents: [], // Computed after all entries are processed
                 ...(name ? { name } : {}),
                 ...(triggers && triggers.length > 0 ? { triggers } : {}),
@@ -915,6 +968,7 @@ export async function buildIndex(cwd, options = {}) {
         }
     }
     // Build dependency graph and compute dependents
+    let markdownLinkEdgeCount = 0;
     for (const entry of Object.values(entries)) {
         if (!depGraph[entry.path]) {
             depGraph[entry.path] = { upstream: [], downstream: [] };
@@ -923,17 +977,13 @@ export async function buildIndex(cwd, options = {}) {
             // Normalize: check if referenced path exists in the index
             const normalizedDep = Object.keys(entries).find(p => p === dep || p.endsWith(dep));
             if (normalizedDep && normalizedDep !== entry.path) {
-                const upEdge = { path: normalizedDep, type: 'depends-on' };
-                depGraph[entry.path].upstream.push(upEdge);
-                if (!depGraph[normalizedDep]) {
-                    depGraph[normalizedDep] = { upstream: [], downstream: [] };
-                }
-                const downEdge = { path: entry.path, type: 'depends-on' };
-                depGraph[normalizedDep].downstream.push(downEdge);
-                // Also update the dependents field on the target entry
-                if (entries[normalizedDep]) {
-                    entries[normalizedDep].dependents.push(entry.path);
-                }
+                addDependencyEdge(depGraph, entries, entry.path, normalizedDep, 'depends-on');
+            }
+        }
+        for (const link of entry.markdownLinks ?? []) {
+            const normalizedDep = resolveMarkdownLinkDependency(cwd, entry.path, link, entries, graph);
+            if (normalizedDep && addDependencyEdge(depGraph, entries, entry.path, normalizedDep, 'markdown-link')) {
+                markdownLinkEdgeCount++;
             }
         }
     }
@@ -1069,6 +1119,7 @@ export async function buildIndex(cwd, options = {}) {
         tagDistribution: tagDist,
         graphMetrics: {
             totalEdges,
+            markdownLinkEdges: markdownLinkEdgeCount,
             ...(citationMetrics ? {
                 canonicalEdges: citationMetrics.canonicalEdges,
                 outgoingDeclarations: citationMetrics.outgoingDeclarations,

package/dist/src/artifacts/index-files.js

@@ -31,22 +31,40 @@ export function indexPathFor(cwd, fullPath, graph) {
         return toPosixPath(relative);
     return fullPath;
 }
-/** Recursively find indexable files, excluding hidden directories such as .index. */
 export function findArtifactFiles(dir, extensions = DEFAULT_INDEX_EXTENSIONS) {
+    return walkArtifactFiles(dir, extensions, new Set());
+}
+/** Recursively find indexable files, excluding hidden directories such as .index. */
+function walkArtifactFiles(dir, extensions, seenRealDirs) {
     const results = [];
     if (!fs.existsSync(dir))
         return results;
+    let realDir;
+    try {
+        realDir = fs.realpathSync(dir);
+    }
+    catch {
+        return results;
+    }
+    if (seenRealDirs.has(realDir))
+        return results;
+    seenRealDirs.add(realDir);
     const entries = fs.readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
         const fullPath = path.join(dir, entry.name);
-        if (entry.isSymbolicLink() && !fs.existsSync(fullPath))
+        let stat;
+        try {
+            stat = fs.statSync(fullPath);
+        }
+        catch {
             continue;
-        if (entry.isDirectory()) {
+        }
+        if (stat.isDirectory()) {
             if (entry.name.startsWith('.'))
                 continue;
-            results.push(...findArtifactFiles(fullPath, extensions));
+            results.push(...walkArtifactFiles(fullPath, extensions, seenRealDirs));
         }
-        else if (extensions.some(extension => entry.name.endsWith(extension))) {
+        else if (stat.isFile() && extensions.some(extension => entry.name.endsWith(extension))) {
             results.push(fullPath);
         }
     }
@@ -55,6 +73,9 @@ export function findArtifactFiles(dir, extensions = DEFAULT_INDEX_EXTENSIONS) {
 /** Return the exact current source-file set used by a standard graph build. */
 export async function collectGraphIndexFiles(cwd, graph) {
     const config = graph ? GRAPH_CONFIGS[graph] : undefined;
+    if (graph && !config) {
+        throw new Error(`Unknown graph: ${graph}`);
+    }
     const scanDirs = config
         ? config.scanDirs.map(directory => resolveGraphScanDir(cwd, directory))
         : [resolveProjectAiwgDir(cwd)];

package/dist/src/artifacts/query-engine.js

@@ -181,7 +181,7 @@ const SCORE_STOPWORDS = new Set([
     'with', 'into', 'from', 'is', 'are', 'be', 'i', 'we', 'my',
     // pronouns / determiners / fillers
     'it', 'you', 'me', 'us', 'your', 'our', 'this', 'that', 'these', 'those',
-    'there', 'here', 'some', 'any', 'all', 'also', 'please', 'about',
+    'there', 'here', 'some', 'any', 'all', 'also', 'please', 'about', 'project',
     // question words
     'how', 'what', 'which', 'where', 'when', 'who', 'why',
     // asking / request verbs ("find a skill that handles …")
@@ -191,6 +191,7 @@ const SCORE_STOPWORDS = new Set([
     // AIWG meta-type nouns — zero discriminating signal in a discover query
     'aiwg', 'skill', 'skills', 'agent', 'agents', 'command', 'commands',
     'rule', 'rules', 'schema', 'schemas', 'flow', 'flows', 'workflow', 'workflows',
+    'template', 'templates',
 ]);
 /**
  * Tokenize a query phrase into lowercased keywords for multi-word
@@ -200,8 +201,18 @@ const SCORE_STOPWORDS = new Set([
 function tokenize(text) {
     return text
         .toLowerCase()
-        .split(/[^a-z0-9-]+/)
-        .filter(t => t.length > 1 && !SCORE_STOPWORDS.has(t));
+        .split(/[^a-z0-9]+/)
+        .filter(t => t.length > 1 && !SCORE_STOPWORDS.has(t))
+        .map(token => token.length > 4 && token.endsWith('s') && !token.endsWith('ss')
+        ? token.slice(0, -1)
+        : token);
+}
+function matchedFieldTokens(queryTokens, field) {
+    const fieldTokens = new Set(tokenize(field));
+    return queryTokens.filter(token => fieldTokens.has(token));
+}
+function fieldContainsQuery(field, queryTokens) {
+    return containsTokenSequence(tokenize(field), queryTokens);
 }
 /**
  * Score a metadata entry against a keyword query.
@@ -297,6 +308,7 @@ function scoreEntryDetailed(entry, text, opts = {}) {
     const personaIdentitySuppressed = diagnoseFacetActivations(text).some((activation) => activation.facet === 'persona-identity' && activation.status === 'suppressed');
     let score = 0;
     const matches = [];
+    const creditedTokens = new Set();
     const finish = (uncappedScore = score, cap = 1) => ({
         score: Math.min(uncappedScore, cap),
         diagnostic: {
@@ -311,6 +323,17 @@ function scoreEntryDetailed(entry, text, opts = {}) {
         score += contribution;
         matches.push({ ...match, contribution });
     };
+    const addTokenMatch = (contributionPerToken, hits, match) => {
+        const newlyMatched = hits.filter(token => !creditedTokens.has(token));
+        if (newlyMatched.length === 0)
+            return;
+        newlyMatched.forEach(token => creditedTokens.add(token));
+        addMatch(contributionPerToken * newlyMatched.length, {
+            ...match,
+            matched_tokens: newlyMatched,
+            query_token_coverage: tokens.length > 0 ? newlyMatched.length / tokens.length : 0,
+        });
+    };
     // Exact-name floor (#1233) — if the query (normalized) exactly matches
     // the entry's canonical name, this is the artifact the user is asking
     // for and it must surface at the top regardless of how cluttered the
@@ -422,14 +445,12 @@ function scoreEntryDetailed(entry, text, opts = {}) {
                 });
             }
             else if (useMultiToken) {
-                const hits = tokens.filter(t => trigger.includes(t));
+                const hits = matchedFieldTokens(tokens, trigger);
                 if (overlapOK(hits.length)) {
-                    addMatch(0.06 * 4 * (hits.length / tokens.length), {
+                    addTokenMatch(0.1 * 4, hits, {
                         field: 'trigger',
                         match: 'token-overlap',
                         value: trigger,
-                        matched_tokens: hits,
-                        query_token_coverage: hits.length / tokens.length,
                     });
                 }
             }
@@ -437,7 +458,7 @@ function scoreEntryDetailed(entry, text, opts = {}) {
     }
     // Capability description (2x weight) — full phrase first, then tokens
     if (capabilityLower) {
-        if (capabilityLower.includes(lower)) {
+        if (fieldContainsQuery(capabilityLower, tokens)) {
             addMatch(0.2 * 2, {
                 field: 'capability',
                 match: 'contained-phrase',
@@ -445,20 +466,18 @@ function scoreEntryDetailed(entry, text, opts = {}) {
             });
         }
         else if (useMultiToken) {
-            const hits = tokens.filter(t => capabilityLower.includes(t));
+            const hits = matchedFieldTokens(tokens, capabilityLower);
             if (overlapOK(hits.length)) {
-                addMatch(0.1 * 2 * (hits.length / tokens.length), {
+                addTokenMatch(0.1 * 2, hits, {
                     field: 'capability',
                     match: 'token-overlap',
                     value: entry.capability,
-                    matched_tokens: hits,
-                    query_token_coverage: hits.length / tokens.length,
                 });
             }
         }
     }
     // Title (3x weight)
-    if (titleLower.includes(lower)) {
+    if (fieldContainsQuery(titleLower, tokens)) {
         addMatch(0.3 * 3, {
             field: 'title',
             match: titleLower === lower ? 'exact' : 'contained-phrase',
@@ -469,93 +488,83 @@ function scoreEntryDetailed(entry, text, opts = {}) {
         }
     }
     else if (useMultiToken) {
-        const hits = tokens.filter(t => titleLower.includes(t));
+        const hits = matchedFieldTokens(tokens, titleLower);
         if (overlapOK(hits.length)) {
-            addMatch(0.08 * 3 * (hits.length / tokens.length), {
+            addTokenMatch(0.08 * 3, hits, {
                 field: 'title',
                 match: 'token-overlap',
                 value: entry.title,
-                matched_tokens: hits,
-                query_token_coverage: hits.length / tokens.length,
             });
         }
     }
     // Tags (2x weight)
     for (const tag of tagsLower) {
-        if (tag.includes(lower)) {
+        if (fieldContainsQuery(tag, tokens)) {
             addMatch(0.2 * 2, { field: 'tag', match: 'contained-phrase', value: tag });
         }
         else if (useMultiToken) {
-            const hits = tokens.filter(t => tag.includes(t));
+            const hits = matchedFieldTokens(tokens, tag);
             if (overlapOK(hits.length)) {
-                addMatch(0.05 * 2 * (hits.length / tokens.length), {
+                addTokenMatch(0.05 * 2, hits, {
                     field: 'tag',
                     match: 'token-overlap',
                     value: tag,
-                    matched_tokens: hits,
-                    query_token_coverage: hits.length / tokens.length,
                 });
             }
         }
     }
     // Structure-aware language terms (1.5x weight). These are deliberately
     // below declared triggers/capabilities but above generic body summaries.
-    if (searchTermsLower.includes(lower)) {
+    if (fieldContainsQuery(searchTermsLower, tokens)) {
         addMatch(0.18 * 1.5, { field: 'search_terms', match: 'contained-phrase' });
     }
     else if (useMultiToken) {
-        const hits = tokens.filter(t => searchTermsLower.includes(t));
+        const hits = matchedFieldTokens(tokens, searchTermsLower);
         if (overlapOK(hits.length)) {
-            addMatch(0.06 * 1.5 * (hits.length / tokens.length), {
+            addTokenMatch(0.06 * 1.5, hits, {
                 field: 'search_terms',
                 match: 'token-overlap',
-                matched_tokens: hits,
-                query_token_coverage: hits.length / tokens.length,
             });
         }
     }
     // Exact declarative kind and physical source classification are compact,
     // useful routing signals (e.g. FlowPlaybook vs OpsInventory; runbook that
     // originated under templates/).
-    if (kindLower.includes(lower)) {
+    if (fieldContainsQuery(kindLower, tokens)) {
         addMatch(0.15, { field: 'kind', match: 'contained-phrase', value: entry.kind });
     }
-    if (sourceTypeLower.includes(lower)) {
+    if (fieldContainsQuery(sourceTypeLower, tokens)) {
         addMatch(0.08, { field: 'source_type', match: 'contained-phrase', value: entry.sourceType });
     }
     // Summary (1x weight)
-    if (summaryLower.includes(lower)) {
+    if (fieldContainsQuery(summaryLower, tokens)) {
         addMatch(0.15, { field: 'summary', match: 'contained-phrase' });
     }
     else if (useMultiToken) {
-        const hits = tokens.filter(t => summaryLower.includes(t));
+        const hits = matchedFieldTokens(tokens, summaryLower);
         if (overlapOK(hits.length)) {
-            addMatch(0.04 * (hits.length / tokens.length), {
+            addTokenMatch(0.04, hits, {
                 field: 'summary',
                 match: 'token-overlap',
-                matched_tokens: hits,
-                query_token_coverage: hits.length / tokens.length,
             });
         }
     }
     // Path (0.5x weight)
-    if (pathLower.includes(lower)) {
+    if (fieldContainsQuery(pathLower, tokens)) {
         addMatch(0.1, { field: 'path', match: 'contained-phrase', value: entry.path });
     }
     else if (useMultiToken) {
-        const hits = tokens.filter(t => pathLower.includes(t));
+        const hits = matchedFieldTokens(tokens, pathLower);
         if (overlapOK(hits.length)) {
-            addMatch(0.03 * (hits.length / tokens.length), {
+            addTokenMatch(0.03, hits, {
                 field: 'path',
                 match: 'token-overlap',
                 value: entry.path,
-                matched_tokens: hits,
-                query_token_coverage: hits.length / tokens.length,
             });
         }
     }
     // Type (0.5x weight)
-    if (typeLower.includes(lower)) {
+    if (fieldContainsQuery(typeLower, tokens)) {
         addMatch(0.1, { field: 'type', match: 'contained-phrase', value: entry.type });
     }
     return finish();
@@ -1078,36 +1087,27 @@ export async function discoverCapability(cwd, params) {
     // lexical ranking so canonical domain phrases rank their owning capability
     // top-K instead of being out-scored by artifacts that merely mention the
     // word. Facet activation can also rescue an otherwise-empty strict pass.
-    let scored = dedupeDiscoverResults(await applyFacetFusion(strictScored, candidates, params.phrase)).slice(0, limit);
-    // #1561 — verbose-query fallback. A wordy full-sentence query
-    // ("find me a skill that handles intake forms") dilutes the token hit ratio
-    // below the strict ceil(n/2) overlap gate and returns nothing, training
-    // agents to conclude "no skill exists" — the exact decline-without-search
-    // failure the skill-discovery rule guards against. When the strict pass
-    // dead-ends, re-score with a relaxed (single-hit) overlap so the meaningful
-    // tokens still surface ranked candidates rather than an empty set.
-    let relaxed = false;
-    if (scored.length === 0) {
-        // Floor the relaxed pass so a single incidental path/summary token hit
-        // (~0.006–0.008) doesn't surface as noise. Capability/title/trigger field
-        // hits land ~0.04+, so this keeps meaningful matches while dropping junk —
-        // if nothing clears the floor, we fall through to the no-match hint, which
-        // is more honest than surfacing a 0.01 path match.
-        const RELAXED_MIN_SCORE = 0.02;
-        const relaxedFull = candidates
-            .map(entry => {
-            const detailed = scoreEntryDetailed(entry, params.phrase, { relaxOverlap: true });
+    // #154 — a strict result anywhere in the corpus must not suppress relevant
+    // partial matches for a natural-language query. Score the relaxed pass on
+    // matched terms (unmatched terms do not divide the score), apply a noise
+    // floor, and union it with strict matches before ranking. Word-boundary
+    // token matching keeps this from resurrecting substring noise such as UX in
+    // Linux.
+    const RELAXED_MIN_SCORE = 0.02;
+    const strictPaths = new Set(strictScored.map(result => result.entry.path));
+    const combinedByPath = new Map(strictScored.map(result => [result.entry.path, result]));
+    for (const entry of candidates) {
+        const detailed = scoreEntryDetailed(entry, params.phrase, { relaxOverlap: true });
+        if (detailed.score < RELAXED_MIN_SCORE)
+            continue;
+        const existing = combinedByPath.get(entry.path);
+        if (!existing || detailed.score > existing.score) {
+            combinedByPath.set(entry.path, { entry, score: detailed.score });
             lexicalDiagnostics.set(entry.path, detailed.diagnostic);
-            return { entry, score: detailed.score };
-        })
-            .filter(r => r.score >= RELAXED_MIN_SCORE)
-            .sort(compareDiscoverResults);
-        const relaxedScored = dedupeDiscoverResults(await applyFacetFusion(relaxedFull, candidates, params.phrase)).slice(0, limit);
-        if (relaxedScored.length > 0) {
-            scored = relaxedScored;
-            relaxed = true;
         }
     }
+    const scored = dedupeDiscoverResults(await applyFacetFusion(Array.from(combinedByPath.values()).sort(compareDiscoverResults), candidates, params.phrase)).slice(0, limit);
+    const relaxed = scored.some(result => !strictPaths.has(result.entry.path));
     const queryTimeMs = Date.now() - startTime;
     /**
      * Resolve a stored framework-graph path to an absolute AIWG_ROOT