@aiwg/cli 2026.10.1 → 2026.10.4

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

@@ -8,10 +8,14 @@
  * @source @src/artifacts/types.ts
  * @tests @test/unit/artifacts/query-engine.test.ts
  */
+import { refreshFrameworkCapabilities, resolveFrameworkCorpusRoot, isCorpusBundleInstalled } from './framework-capabilities.js';
+import { resolveFrameworkIndexRoot } from './framework-index-paths.js';
+import { ensureRelations, selectPrebuiltRelations, emptyRuleStats } from './relations.js';
 import { minimatch } from 'minimatch';
+import { inferRuleActivation } from '../rules/activation.mjs';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { OPERATIONAL_DISCOVERY_TYPES, OPERATIONAL_SHOW_TYPES, isOperationalShowType, loadGlobalGraphConfigs, } from './types.js';
+import { OPERATIONAL_DISCOVERY_TYPES, OPERATIONAL_SHOW_TYPES, isOperationalShowType, loadGlobalGraphConfigs, getGraphIndexDir, } from './types.js';
 import { loadMetadataIndex, loadGraphIndexFile } from './index-reader.js';
 import { bm25Rank } from './fulltext.js';
 import { parseFrontmatter } from './index-builder.js';
@@ -859,21 +863,6 @@ function showHintForDiscoverResult(entry, id) {
     }
     return `aiwg show ${id}`;
 }
-async function getAiwgRootForDiscover() {
-    if (process.env.AIWG_ROOT)
-        return process.env.AIWG_ROOT;
-    try {
-        const mod = await import('../channel/manager.mjs');
-        if (typeof mod.getFrameworkRoot === 'function') {
-            const r = await mod.getFrameworkRoot();
-            return r || null;
-        }
-    }
-    catch {
-        // channel manager unavailable — fall through
-    }
-    return null;
-}
 export async function discoverCapability(cwd, params) {
     loadGlobalGraphConfigs();
     const startTime = Date.now();
@@ -888,7 +877,7 @@ export async function discoverCapability(cwd, params) {
     const limit = params.limit ?? 5;
     // For framework-graph entries, anchor returned paths to AIWG_ROOT so
     // they resolve from any project working directory (#1217).
-    const aiwgRoot = await getAiwgRootForDiscover();
+    const aiwgRoot = resolveFrameworkIndexRoot(cwd);
     // Source: prefer `framework` graph (built post-deploy), fall back to
     // project / codebase / legacy depending on what's available.
     let entries = [];
@@ -897,10 +886,24 @@ export async function discoverCapability(cwd, params) {
     let resourceSource = params.resourceSource ?? 'local';
     let resolvedWebRelease;
     let verifiedSourcePaths;
+    const prebuiltRelations = resourceSource !== 'web' && (!params.graph || params.graph === 'framework')
+        ? selectPrebuiltRelations(cwd).reader : null;
+    if ((!prebuiltRelations || backend === 'local') && resourceSource !== 'web' && (!params.graph || params.graph === 'framework')) {
+        const root = resolveFrameworkCorpusRoot(cwd) ?? aiwgRoot;
+        if (root) {
+            try {
+                await refreshFrameworkCapabilities(root, backend === 'fortemi-core');
+            }
+            catch (error) {
+                console.error(`Warning: capability index refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
     if (resourceSource === 'auto') {
         const { loadFortemiCoreMetadataEntries } = await import('./fortemi-core-query-adapter.js');
         const localGraphs = params.graph ? [params.graph] : defaultCapabilityGraphs(cwd);
-        const localAvailable = localGraphs.some((graph) => loadFortemiCoreMetadataEntries(cwd, graph).entries.length > 0);
+        const localAvailable = localGraphs.some((graph) => loadFortemiCoreMetadataEntries(cwd, graph).entries.length > 0
+            || Object.keys(loadGraphIndexFile(cwd, 'metadata.json', graph)?.entries ?? {}).length > 0);
         resourceSource = localAvailable ? 'local' : 'web';
     }
     if (resourceSource === 'web') {
@@ -949,6 +952,16 @@ export async function discoverCapability(cwd, params) {
                     continue;
                 }
             }
+            if (loaded.sourceIndexNewer && resourceSource === 'local') {
+                // Do not silently omit a graph whose derived cache is stale. Rank its
+                // current source metadata, without consulting scores from the old cache.
+                const index = loadGraphIndexFile(cwd, 'metadata.json', graph);
+                if (index) {
+                    console.error(`Warning: ${graph} capability cache is unavailable or stale; using the local ${graph} index. ${loaded.reason}`);
+                    entries.push(...Object.values(index.entries).map((entry) => withIndexProvenance(entry, graph)));
+                    continue;
+                }
+            }
             if (loaded.reason) {
                 unavailableReason ??= loaded.reason;
                 if (graph === 'framework' && !params.graph) {
@@ -992,6 +1005,7 @@ export async function discoverCapability(cwd, params) {
                             : {}),
                     },
                     results: [],
+                    rule_stats: emptyRuleStats(),
                     total: 0,
                     hint: unavailableReason,
                 }, null, 2));
@@ -1011,47 +1025,10 @@ export async function discoverCapability(cwd, params) {
         // discover is EXCLUSIVELY the agentic-capability surface (#1545): source
         // the `framework` graph (deployed AIWG capabilities) + project-local
         // capability artifacts. NEVER `codebase` — source code is not a capability
-        // surface. discover leverages indexing transparently: if the framework
-        // index is missing but its source is present, build it once (incremental
-        // thereafter) so discover Just Works without the operator picking a graph.
-        let fwIdx = loadGraphIndexFile(cwd, 'metadata.json', 'framework');
-        if (!fwIdx) {
-            // The framework graph is shared (XDG) and `defaultBuild: false`, so a bare
-            // `aiwg index build` never (re)builds it — only `aiwg use` or an explicit
-            // `--graph framework` does. When it's absent, build it from wherever the
-            // AIWG source lives: `cwd/agentic/code` when inside the AIWG repo, else
-            // `$AIWG_ROOT/agentic/code` for a USER project (#1541 — opencode users sit
-            // in their own project, not the AIWG repo, so a cwd-only check left
-            // discover unable to find deployed commands like address-issues). buildIndex
-            // scans <root>/agentic/code and writes to the cwd-independent XDG dir, so
-            // reading back via cwd still resolves the freshly-built shared index.
-            const buildRoot = fs.existsSync(path.join(cwd, 'agentic', 'code'))
-                ? cwd
-                : aiwgRoot && fs.existsSync(path.join(aiwgRoot, 'agentic', 'code'))
-                    ? aiwgRoot
-                    : null;
-            if (buildRoot) {
-                const { buildIndex } = await import('./index-builder.js');
-                if (!params.json)
-                    console.error('Building capability index (first run)…');
-                // buildIndex writes progress to stdout. In --json mode that would corrupt
-                // the JSON envelope the caller parses, so silence stdout for the duration
-                // of the auto-build (the build is incidental to the query).
-                const origLog = console.log;
-                if (params.json)
-                    console.log = () => { };
-                try {
-                    await buildIndex(buildRoot, { graph: 'framework', explicit: false });
-                }
-                catch {
-                    /* non-fatal — fall through to whatever index is available */
-                }
-                finally {
-                    console.log = origLog;
-                }
-                fwIdx = loadGraphIndexFile(cwd, 'metadata.json', 'framework');
-            }
-        }
+        // surface. The framework
+        // index is reconciled with its source above, including existing indexes
+        // left behind by an older runtime or a different checkout.
+        const fwIdx = loadGraphIndexFile(cwd, 'metadata.json', 'framework');
         const includeUser = projectAllowsUserIndices(cwd);
         // Project-local operational artifacts authored in this project. The
         // DEFAULT_DISCOVER_TYPES filter keeps non-capability project artifacts
@@ -1082,6 +1059,7 @@ export async function discoverCapability(cwd, params) {
             console.log(JSON.stringify({
                 query: { phrase: params.phrase, types },
                 results: [],
+                rule_stats: emptyRuleStats(),
                 total: 0,
                 hint,
             }, null, 2));
@@ -1191,6 +1169,16 @@ export async function discoverCapability(cwd, params) {
             ? `No capability matched "${params.phrase}" among ${entries.length} Fortemi Core static-cache capabilities. Try a broader phrase or a \`--type\` filter. If the local index changed, refresh the cache with \`aiwg index sync ${params.graph ? `--graph ${params.graph}` : '--all'}\`, or pass \`--backend local\` to use the legacy local index.`
             : `No capability matched "${params.phrase}" among ${entries.length} indexed capabilities. Try a broader phrase or a \`--type\` filter. If you just installed or authored capabilities, refresh discovery with \`aiwg use <framework>\` (or \`aiwg index build\`).`
         : null;
+    const relations = resourceSource === 'local' && (!params.graph || params.graph === 'framework')
+        ? prebuiltRelations ?? await ensureRelations(cwd) : undefined;
+    const governing = scored.map(result => compoundGoverningRules(entries, result.entry, relations ?? undefined, params.phrase));
+    const responseRules = new Map();
+    for (const item of governing.flat()) {
+        const key = `${item.rule.type}:${item.rule.path}`, prior = responseRules.get(key);
+        responseRules.set(key, { rule: item.rule, applicability: [...new Set([...(prior?.applicability ?? []), ...item.applicability])] });
+    }
+    const responseFields = governingRuleFields([...responseRules.values()]);
+    const responseRuleStats = governingRuleStats([...responseRules.values()]);
     const includePaths = params.includePaths ?? true;
     const facetActivations = diagnoseFacetActivations(params.phrase);
     const roundDiagnostic = (value) => Math.round(value * 1_000_000) / 1_000_000;
@@ -1228,6 +1216,8 @@ export async function discoverCapability(cwd, params) {
             },
         };
     };
+    const { loadRelations } = await import('./relations.js');
+    const ruleRelations = resourceSource === 'local' ? loadRelations(cwd) ?? (aiwgRoot ? loadRelations(aiwgRoot, cwd) : null) : null;
     if (params.json) {
         const jsonIndent = params.jsonPretty === false ? undefined : 2;
         console.log(JSON.stringify({
@@ -1250,7 +1240,7 @@ export async function discoverCapability(cwd, params) {
                     }
                     : {}),
             },
-            results: scored.map(r => ({
+            results: scored.map((r, resultIndex) => ({
                 id: discoveryIdForEntry(r.entry),
                 ...(includePaths ? { path: resolvePath(r.entry) } : {}),
                 type: r.entry.type,
@@ -1258,9 +1248,14 @@ export async function discoverCapability(cwd, params) {
                 title: r.entry.title,
                 score: Math.round(r.score * 100) / 100,
                 ranking: rankingDiagnostic(r.entry, r.score, r.facetDiagnostics),
+                ...governingRuleFields(governing[resultIndex]),
                 triggers: r.entry.triggers ?? [],
                 capability: r.entry.capability ?? r.entry.summary,
                 kernel: r.entry.kernel ?? false,
+                ...(['skill', 'agent', 'flow', 'command'].includes(r.entry.type) && ruleRelations
+                    && ruleRelations.rulesForTarget(r.entry.type, discoveryIdForEntry(r.entry)).length ? {
+                    startup_rule_stats: ruleRelations.ruleStats(r.entry.type, discoveryIdForEntry(r.entry)),
+                } : {}),
                 provenance: {
                     graph: r.entry.indexGraph ?? null,
                     scope: r.entry.indexScope ?? null,
@@ -1275,6 +1270,8 @@ export async function discoverCapability(cwd, params) {
                     }
                     : {}),
             })),
+            rule_stats: responseRuleStats,
+            ...(responseFields.required_rule_checks ? { required_rule_checks: responseFields.required_rule_checks, rule_check_obligation: RULE_CHECK_OBLIGATION } : {}),
             total: scored.length,
             query_time_ms: queryTimeMs,
             diagnostics: {
@@ -1296,6 +1293,7 @@ export async function discoverCapability(cwd, params) {
     }
     const relaxedNote = relaxed ? ' — relaxed match (verbose query)' : '';
     console.log(`Discovery results for "${params.phrase}" (${scored.length} matches, ${queryTimeMs}ms)${relaxedNote}:`);
+    console.log(statsText(responseRuleStats));
     console.log('');
     for (const diagnostic of facetActivations) {
         if (diagnostic.status === 'suppressed' && diagnostic.reason) {
@@ -1339,6 +1337,12 @@ export async function discoverCapability(cwd, params) {
             `scope ${ranking.tie_breakers.scope}`,
         ].filter((part) => Boolean(part));
         console.log(`   ranking: ${rankingParts.join('; ')}`);
+        if (governing[i].length) {
+            console.log(`   ${statsText(governingRuleStats(governing[i]))}`);
+            console.log(`   ${RULE_CHECK_OBLIGATION}`);
+            for (const { rule, applicability } of governing[i])
+                console.log(`   - ${rule.name ?? rule.path}: ${rule.ruleSummary ?? ''} (${applicability.join('; ')}) — \`${boundRuleDescriptor(rule).show_command}\``);
+        }
         if (r.entry.script) {
             console.log(`   run: ${buildRunHint(r.entry)}`);
         }
@@ -1364,11 +1368,37 @@ function resolveMetadataPath(cwd, aiwgRoot, entry) {
     }
     return path.join(cwd, normalizedPath);
 }
-async function loadShowEntries(cwd, params) {
-    const aiwgRoot = await getAiwgRootForDiscover();
+async function loadShowEntries(cwd, params, compact = false) {
+    const aiwgRoot = resolveFrameworkIndexRoot(cwd);
     const backend = params.backend ?? DEFAULT_ARTIFACT_SEARCH_BACKEND;
     let resourceSource = params.resourceSource ?? 'local';
     let entries = [];
+    let relations;
+    if (compact && resourceSource !== 'web' && (!params.graph || params.graph === 'framework')) {
+        relations = await ensureRelations(cwd) ?? undefined;
+        if (relations?.index.artifacts) {
+            const frameworkEntries = Object.values(relations.index.artifacts).map(entry => withIndexProvenance({
+                phase: '', tags: [], created: '', updated: '', checksum: '', summary: '', dependencies: [], dependents: [], ...entry,
+            }, 'framework'));
+            const localEntries = params.graph ? [] : defaultCapabilityGraphs(cwd).filter(graph => graph !== 'framework')
+                .flatMap(graph => loadLocalCapabilityEntries(cwd, graph));
+            const compactEntries = [...localEntries, ...frameworkEntries];
+            if (findShowMatches(compactEntries, params.typeFilter ?? [...OPERATIONAL_SHOW_TYPES], params.name.trim()).length) {
+                return { entries: compactEntries, aiwgRoot, resourceSource: 'local', relations };
+            }
+        }
+    }
+    if (resourceSource !== 'web' && (!params.graph || params.graph === 'framework')) {
+        const root = resolveFrameworkCorpusRoot(cwd) ?? aiwgRoot;
+        if (root) {
+            try {
+                await refreshFrameworkCapabilities(root, backend === 'fortemi-core' && params.backend !== undefined);
+            }
+            catch (error) {
+                console.error(`Warning: capability index refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
     if (resourceSource === 'auto' && backend === 'fortemi-core') {
         const { loadFortemiCoreMetadataEntries } = await import('./fortemi-core-query-adapter.js');
         const localGraphs = params.graph ? [params.graph] : defaultCapabilityGraphs(cwd);
@@ -1451,24 +1481,59 @@ async function loadShowEntries(cwd, params) {
             process.exit(1);
         }
     }
-    else if (params.graph) {
-        const idx = loadGraphIndexFile(cwd, 'metadata.json', params.graph);
-        if (idx)
-            entries = Object.values(idx.entries).map((entry) => withIndexProvenance(entry, params.graph));
-    }
     else {
-        for (const g of defaultCapabilityGraphs(cwd)) {
-            const idx = loadGraphIndexFile(cwd, 'metadata.json', g);
-            if (idx)
-                entries.push(...Object.values(idx.entries).map((entry) => withIndexProvenance(entry, g)));
+        entries = loadLocalCapabilityEntries(cwd, params.graph);
+    }
+    return { entries, aiwgRoot, resourceSource: 'local', relations };
+}
+/** Local index inputs shared by show and exact rule-binding validation (#2938). */
+export function loadLocalCapabilityEntries(cwd, graph, snapshot) {
+    const entries = [];
+    for (const selectedGraph of graph ? [graph] : defaultCapabilityGraphs(cwd)) {
+        const key = snapshot && `${selectedGraph}:${getGraphIndexDir(cwd, selectedGraph)}`;
+        let selected = key ? snapshot.get(key) : undefined;
+        if (!selected) {
+            const index = loadGraphIndexFile(cwd, 'metadata.json', selectedGraph);
+            selected = index ? Object.values(index.entries).map(entry => withIndexProvenance(entry, selectedGraph)) : [];
+            if (key)
+                snapshot.set(key, selected);
+        }
+        entries.push(...selected);
+    }
+    if (!graph && entries.length === 0) {
+        const legacy = loadMetadataIndex(cwd);
+        if (legacy)
+            entries.push(...Object.values(legacy.entries));
+    }
+    return entries;
+}
+/** Project/user inputs only; package artifacts come from a validated compact table. */
+export function loadLocalOverrideCapabilityEntries(cwd) {
+    const local = defaultCapabilityGraphs(cwd).filter(graph => graph !== 'framework')
+        .flatMap(graph => loadLocalCapabilityEntries(cwd, graph));
+    if (local.length)
+        return local;
+    const canonical = (directory) => {
+        try {
+            return fs.realpathSync(directory);
         }
-        if (entries.length === 0) {
-            const legacy = loadMetadataIndex(cwd);
-            if (legacy)
-                entries.push(...Object.values(legacy.entries));
+        catch {
+            return path.resolve(directory);
         }
-    }
-    return { entries, aiwgRoot, resourceSource: 'local' };
+    };
+    const packageRoot = canonical(resolveFrameworkIndexRoot(cwd));
+    // Retain the legacy PROJECT index, never use the package's full index as a fallback.
+    if (canonical(cwd) === packageRoot)
+        return [];
+    const legacy = loadMetadataIndex(cwd);
+    return Object.values(legacy?.entries ?? {}).filter(entry => {
+        const provenance = entry;
+        if (provenance.indexGraph === 'framework' || provenance.indexScope === 'packaged'
+            || normalizeIndexedPath(entry.path).startsWith('agentic/code/'))
+            return false;
+        const relative = path.relative(packageRoot, path.resolve(cwd, entry.path));
+        return relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
+    }).map(entry => withIndexProvenance(entry, 'project'));
 }
 function findShowMatches(entries, types, needle) {
     const needleLower = needle.toLowerCase();
@@ -1538,6 +1603,57 @@ function findShowMatches(entries, types, needle) {
     }
     return matches;
 }
+/** Preselect exact candidates once; the canonical resolver still owns precedence and ambiguity. */
+export function createRuleBindingTargetResolver(entries) {
+    const candidates = new Map();
+    for (const entry of entries) {
+        if (!['skill', 'agent', 'flow'].includes(entry.type))
+            continue;
+        const normalized = normalizeIndexedPath(entry.path);
+        const basename = path.posix.basename(normalized);
+        const slug = /^(?:SKILL|AGENT|FLOW)\.md$/i.test(basename)
+            ? path.posix.basename(path.posix.dirname(normalized))
+            : basename.replace(/\.[^.]+$/, '');
+        for (const id of new Set([entry.name, discoveryIdForEntry(entry), slug])) {
+            if (typeof id !== 'string')
+                continue;
+            const key = `${entry.type}\0${id}`;
+            const selected = candidates.get(key) ?? [];
+            selected.push(entry);
+            candidates.set(key, selected);
+        }
+    }
+    return (type, id) => resolveRuleBindingTarget(candidates.get(`${type}\0${id}`) ?? [], type, id);
+}
+/** Resolve exact rule binding IDs using the same precedence and ambiguity as show.
+ * Canonical layout slugs remain valid when frontmatter names are display names.
+ * Titles and filesystem paths are deliberately excluded (#2938).
+ */
+export function resolveRuleBindingTarget(entries, type, id) {
+    const exact = entries.filter(entry => {
+        if (entry.type !== type)
+            return false;
+        const normalized = normalizeIndexedPath(entry.path);
+        const basename = path.posix.basename(normalized);
+        const slug = /^(?:SKILL|AGENT|FLOW)\.md$/i.test(basename)
+            ? path.posix.basename(path.posix.dirname(normalized))
+            : basename.replace(/\.[^.]+$/, '');
+        return entry.name === id || discoveryIdForEntry(entry) === id || slug === id;
+    });
+    let matches = findShowMatches(exact, [type], id);
+    // Generated plugin copies (agentic/code/plugins/*) mirror canonical framework
+    // and addon artifacts. Prefer the canonical source when it is unambiguous.
+    if (matches.length > 1) {
+        const canonical = matches.filter(entry => !/(^|\/)agentic\/code\/plugins\//.test(normalizeIndexedPath(entry.path)));
+        if (canonical.length === 1)
+            matches = canonical;
+    }
+    if (matches.length === 0)
+        throw new Error(`Missing ${type} binding target: ${id}`);
+    if (matches.length > 1)
+        throw new Error(`Ambiguous ${type} binding target: ${id}: ${matches.map(entry => entry.path).join(', ')}`);
+    return matches[0];
+}
 async function fortemiRecordForEntry(cwd, entry, sourcePaths) {
     const graph = (entry.indexGraph ?? 'project');
     const { loadFortemiCoreExport } = await import('./fortemi-core-query-adapter.js');
@@ -1762,6 +1878,178 @@ async function findAgentInCorpus(agentsRoot, name, depth = 0) {
     }
     return null;
 }
+/** Build an ephemeral reverse lookup from the already-loaded rule metadata. */
+export function rulesBoundTo(entries, target) {
+    const key = { skill: 'skills', agent: 'agents', flow: 'flows' }[target.type];
+    if (!key)
+        return [];
+    const file = path.basename(normalizeIndexedPath(target.path));
+    const aliases = [target.name, target.title, target.path, discoveryIdForEntry(target),
+        file === 'SKILL.md' ? path.basename(path.dirname(normalizeIndexedPath(target.path))) : file.replace(/\.[^.]+$/, '')]
+        .filter((alias) => !!alias);
+    const seen = new Set();
+    return entries.filter(rule => {
+        if (rule.type !== 'rule' && rule.type !== 'behavior')
+            return false;
+        const patterns = rule.bound_to?.[key];
+        if (!Array.isArray(patterns) || !patterns.some(pattern => typeof pattern === 'string'
+            && aliases.some(alias => alias === pattern || minimatch(alias, pattern, { nonegate: true, nocomment: true }))))
+            return false;
+        const identity = `${rule.type}:${rule.path}`;
+        if (seen.has(identity))
+            return false;
+        seen.add(identity);
+        return true;
+    }).sort((a, b) => (a.name ?? a.path).localeCompare(b.name ?? b.path) || a.path.localeCompare(b.path));
+}
+/** Relationship metadata for shipped targets, merged with project/user contracts. */
+export function relationshipRules(entries, target, relations) {
+    const local = rulesBoundTo(relations ? entries.filter(entry => !normalizeIndexedPath(entry.path).startsWith('agentic/code/')) : entries, target);
+    if (!relations || !['skill', 'agent', 'flow', 'command'].includes(target.type))
+        return local;
+    const asMetadata = (id) => {
+        const rule = relations.index.rules[id];
+        return { path: rule.path, type: rule.type, name: rule.name, activation: rule.activation ?? undefined,
+            bound_to: rule.bound_to, ruleSummary: rule.summary, ruleEnforcement: rule.enforcement ?? undefined, rulePaths: rule.paths, triggers: rule.triggers };
+    };
+    const key = `${target.type}:${discoveryIdForEntry(target)}`;
+    const shipped = Object.hasOwn(relations.index.targets, key)
+        ? relations.rulesForTarget(target.type, discoveryIdForEntry(target)).map(asMetadata)
+        // Project/user overrides keep the old alias/glob behavior using only small records.
+        : rulesBoundTo(Object.keys(relations.index.rules).map(asMetadata), target);
+    const merged = new Map([...local, ...shipped].map(rule => [`${rule.type}:${rule.path}`, rule]));
+    return [...merged.values()].sort((a, b) => (a.name ?? a.path).localeCompare(b.name ?? b.path) || a.path.localeCompare(b.path));
+}
+export const RULE_CHECK_OBLIGATION = 'Before governed work, fetch and follow every required rule below; a discovery summary is not the full rule.';
+function relationMetadata(relations) {
+    return Object.values(relations.index.rules).map(rule => ({ path: rule.path, type: rule.type, name: rule.name,
+        activation: rule.activation ?? undefined, ruleSummary: rule.summary, ruleEnforcement: rule.enforcement ?? undefined,
+        bound_to: rule.bound_to, rulePaths: rule.paths, triggers: rule.triggers }));
+}
+/** Post-ranking enrichment: relationship lookup never loads the full metadata index. */
+export function compoundGoverningRules(entries, target, relations, phrase = '', includeMatches = true, excludeKernel = true) {
+    if (!['skill', 'agent', 'flow', 'command'].includes(target.type))
+        return [];
+    const found = new Map();
+    const add = (rule, why) => {
+        const activation = rule.activation ?? (rule.type === 'behavior' ? 'kernel' : inferRuleActivation(rule.ruleEnforcement));
+        if (excludeKernel && (activation === 'kernel' || rule.kernel || relations?.pinnedRuleIds.has(discoveryIdForEntry(rule))))
+            return;
+        const key = `${rule.type}:${rule.path}`, item = found.get(key) ?? { rule, applicability: [] };
+        if (!item.applicability.includes(why))
+            item.applicability.push(why);
+        found.set(key, item);
+    };
+    for (const rule of relationshipRules(entries, target, relations))
+        add(rule, `bound:${target.type}:${discoveryIdForEntry(target)}`);
+    if (relations && target.type === 'skill' && target.name?.startsWith('projected:')) {
+        for (const id of relations.rulesForTarget('skill', target.name)) {
+            const rule = relationMetadata(relations).find(rule => discoveryIdForEntry(rule) === id);
+            if (rule)
+                add(rule, `projected-flow:${target.name.slice('projected:'.length)}`);
+        }
+    }
+    if (includeMatches) {
+        const query = phrase.toLowerCase();
+        const queryPaths = (phrase.replace(/\\/g, '/').match(/[\w@./*?-]+/g) ?? []).map(value => value.replace(/[.,;:!?]+$/, ''));
+        const corpus = relations ? relationMetadata(relations) : [];
+        const rules = new Map([...corpus, ...entries.filter(entry => ['rule', 'behavior'].includes(entry.type))]
+            .map(rule => [`${rule.type}:${rule.path}`, rule]));
+        for (const rule of rules.values()) {
+            for (const glob of rule.rulePaths ?? [])
+                for (const candidate of [...queryPaths.filter(value => /[./*?]/.test(value) || value === glob), ...(target.governedPaths ?? [])]) {
+                    if (minimatch(candidate, glob, { dot: true, nonegate: true, nocomment: true })
+                        || ((target.governedPaths ?? []).includes(candidate) && minimatch(glob, candidate, { dot: true, nonegate: true, nocomment: true })))
+                        add(rule, `path:${candidate}`);
+                }
+            for (const trigger of rule.triggers ?? []) {
+                const normalized = trigger.trim().toLowerCase();
+                let offset = normalized ? query.indexOf(normalized) : -1;
+                while (offset >= 0) {
+                    if ((offset === 0 || !/\w/.test(query[offset - 1]))
+                        && (offset + normalized.length === query.length || !/\w/.test(query[offset + normalized.length]))) {
+                        add(rule, `trigger:${trigger}`);
+                        break;
+                    }
+                    offset = query.indexOf(normalized, offset + 1);
+                }
+            }
+        }
+    }
+    return [...found.values()].sort((a, b) => (a.rule.name ?? a.rule.path).localeCompare(b.rule.name ?? b.rule.path) || a.rule.path.localeCompare(b.rule.path));
+}
+function boundRuleDescriptor(rule) {
+    return { name: rule.name ?? path.basename(rule.path, '.md'), activation: rule.activation ?? null,
+        summary: rule.ruleSummary ?? '', show_command: `aiwg show ${rule.type} ${rule.name ?? path.basename(rule.path, '.md')}` };
+}
+/** Counts unique attached contracts; every emitted check is required irrespective of severity. */
+export function governingRuleStats(governing) {
+    const stats = emptyRuleStats();
+    for (const { rule } of new Map(governing.map(item => [`${item.rule.type}:${item.rule.path}`, item])).values()) {
+        const enforcement = rule.ruleEnforcement?.toLowerCase() ?? 'unknown', activation = rule.activation ?? 'unknown';
+        stats.by_enforcement[enforcement] = (stats.by_enforcement[enforcement] ?? 0) + 1;
+        stats.by_activation[activation] = (stats.by_activation[activation] ?? 0) + 1;
+        stats.required_checks++;
+    }
+    return stats;
+}
+export function governingRuleFields(governing) {
+    if (!governing.length)
+        return {};
+    return { bound_rules: governing.map(({ rule }) => boundRuleDescriptor(rule)), rule_stats: governingRuleStats(governing),
+        required_rule_checks: governing.map(({ rule, applicability }) => ({ rule_id: discoveryIdForEntry(rule),
+            applicability, fetch_command: `aiwg show ${rule.type} ${discoveryIdForEntry(rule)}` })), rule_check_obligation: RULE_CHECK_OBLIGATION };
+}
+function statsText(stats) {
+    return `rules: ${Object.entries(stats.by_enforcement).map(([level, count]) => `${count} ${level}`).join(', ') || '0'} · activation: ${Object.entries(stats.by_activation).map(([mode, count]) => `${count} ${mode}`).join(', ') || 'none'} · ${stats.required_checks} required checks`;
+}
+export function relationshipRuleStats(entries, target, relations) {
+    const shipped = Object.hasOwn(relations.index.targets, `${target.type}:${discoveryIdForEntry(target)}`);
+    const stats = shipped ? relations.ruleStats(target.type, discoveryIdForEntry(target)) : emptyRuleStats();
+    // Shipped counts are precomputed; project/user contracts and overrides are overlays.
+    const overlay = shipped ? rulesBoundTo(entries.filter(entry => !normalizeIndexedPath(entry.path).startsWith('agentic/code/')), target)
+        : relationshipRules(entries, target, relations);
+    for (const rule of overlay) {
+        const enforcement = rule.ruleEnforcement ?? 'unknown';
+        const activation = rule.activation ?? 'unknown';
+        stats.by_enforcement[enforcement] = (stats.by_enforcement[enforcement] ?? 0) + 1;
+        stats.by_activation[activation] = (stats.by_activation[activation] ?? 0) + 1;
+        if (enforcement === 'critical' || enforcement === 'high')
+            stats.required_checks++;
+    }
+    return stats;
+}
+async function showBindings(entries, target, content, params, read, relations) {
+    const governing = compoundGoverningRules(entries, target, relations, '', false, false);
+    const rules = governing.map(item => item.rule);
+    const boundRules = await Promise.all(rules.map(async (rule) => ({
+        ...boundRuleDescriptor(rule),
+        ...(params.boundRuleBodies ? { content: await read(rule) } : {}),
+    })));
+    // Parse the selected rule for reverse lookup, including corpus-only rules.
+    const targets = target.type === 'rule' || target.type === 'behavior'
+        ? parseFrontmatter(content).data.bound_to : undefined;
+    const boundTo = targets && typeof targets === 'object' && !Array.isArray(targets)
+        ? Object.fromEntries(['skills', 'agents', 'flows'].flatMap(key => {
+            const values = targets[key];
+            const names = Array.isArray(values) ? [...new Set(values.filter((value) => typeof value === 'string' && !!value.trim()))] : [];
+            return names.length ? [[key, names]] : [];
+        })) : {};
+    let text = '';
+    if (boundRules.length) {
+        text += `\n## Bound rules\n\n${RULE_CHECK_OBLIGATION}\n\n${statsText(governingRuleStats(governing))}\n\n` + boundRules.map(rule => `- **${rule.name}**: ${rule.summary} (\`${rule.show_command}\`)`
+            + ('content' in rule ? `\n\n${rule.content}` : '')).join('\n') + '\n';
+    }
+    if (Object.keys(boundTo).length) {
+        text += '\n## Bound targets\n\n' + Object.entries(boundTo)
+            .map(([key, names]) => `- ${key}: ${names.map(name => `\`${name}\``).join(', ')}`).join('\n') + '\n';
+    }
+    return { fields: {
+            ...governingRuleFields(governing),
+            ...(boundRules.length ? { bound_rules: boundRules } : {}),
+            ...(Object.keys(boundTo).length ? { bound_to: boundTo } : {}),
+        }, text };
+}
 /**
  * Read and emit the full text of a specific artifact (typically a
  * SKILL.md). Consumers don't need to know where AIWG stores skills —
@@ -1785,7 +2073,7 @@ export async function showArtifact(cwd, params) {
     const types = params.typeFilter && params.typeFilter.length > 0
         ? params.typeFilter
         : [...OPERATIONAL_SHOW_TYPES];
-    const { entries, aiwgRoot, resourceSource, webRelease, } = await loadShowEntries(cwd, params);
+    const { entries, aiwgRoot, resourceSource, webRelease, relations, } = await loadShowEntries(cwd, params, true);
     if (entries.length === 0 && params.backend !== 'fortemi-core') {
         console.error('Error: No artifact index found.');
         console.error('Run `aiwg index build --graph framework` (or `aiwg use <framework>`) first.');
@@ -1796,7 +2084,7 @@ export async function showArtifact(cwd, params) {
     if (matches.length === 0) {
         // Corpus fallback (#1221): when the artifact isn't in any indexed graph,
         // scan the AIWG_ROOT corpus for a likely match and render it with an
-        // "(uninstalled)" banner. This keeps `aiwg show` useful in workspaces
+        // installation-aware banner. This keeps `aiwg show` useful in workspaces
         // where the operator hasn't run `aiwg use` yet, or where the framework
         // index is stale, rather than exiting with a misleading "not found".
         if (resourceSource === 'local' && aiwgRoot && params.backend !== 'fortemi-core') {
@@ -1811,34 +2099,49 @@ export async function showArtifact(cwd, params) {
                     console.error(`Error reading ${corpusMatch.path}: ${e.message ?? String(err)}`);
                     process.exit(1);
                 }
-                const installHint = corpusMatch.bundleKind && corpusMatch.bundleId
-                    ? `Run \`aiwg use ${corpusMatch.bundleId}\` to install this ${corpusMatch.bundleKind} into the workspace.`
-                    : 'Run `aiwg index build --graph framework` to refresh the artifact index.';
+                const localPin = corpusMatch.type === 'rule' ? (await import('../rules/pin-state.js')).rulePinState(cwd, aiwgRoot).rules.find(rule => rule.path === corpusMatch.path) : undefined;
+                const installed = await isCorpusBundleInstalled(cwd, aiwgRoot, corpusMatch.bundleKind, corpusMatch.bundleId);
+                const installHint = installed
+                    ? 'The installed bundle is missing from this index. Run `aiwg index build --graph framework` to refresh it.'
+                    : corpusMatch.bundleKind && corpusMatch.bundleId
+                        ? `Run \`aiwg use ${corpusMatch.bundleId}\` to install this ${corpusMatch.bundleKind} into the workspace.`
+                        : 'Run `aiwg index build --graph framework` to refresh the artifact index.';
+                const bindings = await showBindings(entries, {
+                    path: corpusMatch.path, type: corpusMatch.type, name: needle, title: needle,
+                }, content, params, rule => fs.readFile(resolveMetadataPath(cwd, aiwgRoot, rule), 'utf8'), relations);
                 if (params.json) {
                     console.log(JSON.stringify({
+                        ...bindings.fields,
                         path: corpusMatch.path,
                         type: corpusMatch.type,
                         title: needle,
                         kernel: false,
-                        uninstalled: true,
+                        uninstalled: !installed,
+                        ...(localPin ? { local_pin: localPin } : {}),
                         hint: installHint,
                         content,
                     }, null, 2));
                     return;
                 }
-                // Plain text mode: prepend a banner so consumers see the artifact is
-                // corpus-only, then stream the body.
+                // Plain text mode: distinguish a missing index entry from an
+                // uninstalled bundle, then stream the body.
                 const banner = [
-                    '<!-- AIWG: corpus-only artifact — not in the indexed workspace.',
+                    installed
+                        ? '<!-- AIWG: installed bundle artifact — not in the selected index.'
+                        : '<!-- AIWG: corpus-only artifact — not in the indexed workspace.',
                     `     ${installHint}`,
                     '     Origin: ' + corpusMatch.path,
                     '-->',
                     '',
                 ].join('\n');
                 process.stdout.write(banner);
+                if (localPin)
+                    process.stdout.write(`Pinned locally: kernel (canonical ${localPin.canonical_activation}; ${localPin.matches.map(match => match.source).join(', ')}).\n`);
                 process.stdout.write(content);
                 if (!content.endsWith('\n'))
                     process.stdout.write('\n');
+                if (bindings.text)
+                    process.stdout.write(bindings.text);
                 return;
             }
         }
@@ -1925,6 +2228,20 @@ export async function showArtifact(cwd, params) {
             process.exit(1);
         }
     }
+    const localPin = entry.type === 'rule' ? (await import('../rules/pin-state.js')).rulePinState(cwd, aiwgRoot ?? cwd).rules.find(rule => rule.path === filePath) : undefined;
+    const bindings = await showBindings(entries, entry, content, params, async (rule) => {
+        if (resourceSource === 'local')
+            return fs.readFile(resolvePath(rule), 'utf8');
+        const { logicalIdFromFirstPartyPath, resolveAiwgResourceBytes } = await import('../resources/resolver.js');
+        const logicalId = logicalIdFromFirstPartyPath(rule.path);
+        if (!logicalId || !webRelease)
+            throw new Error(`Cannot resolve bound rule: ${rule.path}`);
+        const resolved = await resolveAiwgResourceBytes(logicalId, {
+            source: 'web', frameworkRoot: aiwgRoot ?? cwd, webRelease,
+            webReleaseOptions: params.webReleaseOptions, offline: params.offline,
+        });
+        return resolved.bytes.toString('utf8');
+    }, relations);
     if (params.json) {
         const providerModels = resourceSource === 'local'
             ? await loadProviderModelMetadata(cwd, aiwgRoot)
@@ -1956,21 +2273,26 @@ export async function showArtifact(cwd, params) {
                 ? { executable: true, run_hint: buildRunHint(entry) }
                 : {}),
             ...(providerModels ? { providerModels } : {}),
+            ...bindings.fields,
+            ...(localPin ? { local_pin: localPin } : {}),
             content,
         }, null, 2));
         return;
     }
-    // Plain mode: stream the file content unmodified so the consumer
-    // (agent or operator) sees exactly what the source authored.
+    // Stream the authored content first; append binding guidance only when present.
     // #1227 — for script-bearing skills, prepend a one-line banner so
     // agents reading the body immediately see the skill is executable.
     if (entry.script) {
         const hint = buildRunHint(entry);
         process.stdout.write(`<!-- AIWG: executable skill — run via: ${hint} -->\n`);
     }
+    if (localPin)
+        process.stdout.write(`Pinned locally: kernel (canonical ${localPin.canonical_activation}; ${localPin.matches.map(match => match.source).join(', ')}).\n`);
     process.stdout.write(content);
     if (!content.endsWith('\n'))
         process.stdout.write('\n');
+    if (bindings.text)
+        process.stdout.write(bindings.text);
 }
 export async function showMetadata(cwd, params) {
     loadGlobalGraphConfigs();