@aiwg/cli 2026.10.3 → 2026.10.5

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

@@ -16,13 +16,15 @@ import { load as loadYaml } from 'js-yaml';
 import { validateDecisionDocument } from '../decision/validate.js';
 import { parseDecisionJson, parseDecisionYaml } from '../decision/entry.js';
 import { validateGateDocument } from '../gates/schema.js';
-import { DEFAULT_INDEX_EXTENSIONS, INDEX_EXTRACTOR_VERSION, INDEX_VERSION, INDEX_DIR, OPERATIONAL_DISCOVERY_TYPES, PHASE_DIRECTORIES, GRAPH_CONFIGS, TEMPLATE_INDEX_EXTENSIONS, resolveGraphScanDir, loadUserGraphConfigs, loadGlobalGraphConfigs, } from './types.js';
+import { INDEX_EXTRACTOR_VERSION, INDEX_VERSION, INDEX_DIR, OPERATIONAL_DISCOVERY_TYPES, PHASE_DIRECTORIES, GRAPH_CONFIGS, TEMPLATE_INDEX_EXTENSIONS, resolveGraphScanDir, loadUserGraphConfigs, loadGlobalGraphConfigs, resolveGraphBackendType, } from './types.js';
 import { parseCitationSidecar, citationResultToEdges, buildRefToPathMap } from './citation-parser.js';
 import { writeIndexFile, resolveIndexDir, loadGraphIndexFile } from './index-reader.js';
 import { loadManifest, writeManifest, statMatches, makeEntry } from './checksum-manifest.js';
+import { FRAMEWORK_RELATIONS_REVISION } from './framework-source-digest.js';
 import { normalizeOperationalState } from './operational-state.js';
 import { DEFAULT_PROJECT_AIWG_DIR, resolveProjectAiwgDir, } from '../config/project-artifacts.js';
 import { normalizeStateTransferProjection } from './state-transfer.js';
+import { resolveIndexWorkers, runIndexPreparation } from './index-preparation.js';
 import { collectGraphIndexFiles, findArtifactFiles, indexPathFor } from './index-files.js';
 function absoluteEntryPath(cwd, entryPath, graph) {
     if ((!graph || graph === 'project') && entryPath.startsWith(`${DEFAULT_PROJECT_AIWG_DIR}/`)) {
@@ -56,6 +58,30 @@ export function parseFrontmatter(content) {
         return { data: {}, body: content };
     }
 }
+/** Read the target rule schema tolerantly while older rules remain untagged. */
+export function extractRuleBindings(data, body = '') {
+    const bound_to = {};
+    const raw = data.bound_to;
+    if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+        for (const key of ['skills', 'agents', 'flows']) {
+            const targets = raw[key];
+            if (Array.isArray(targets)) {
+                const names = [...new Set(targets.filter((name) => typeof name === 'string' && name.trim().length > 0))];
+                if (names.length)
+                    bound_to[key] = names;
+            }
+        }
+    }
+    const enforcement = typeof data.enforcement === 'string' ? data.enforcement
+        : body.match(/^\*\*Enforcement Level\*\*:\s*([A-Za-z]+)/m)?.[1];
+    return {
+        ...(enforcement ? { ruleEnforcement: enforcement.trim().toLowerCase() } : {}),
+        ...(Array.isArray(data.paths) ? { rulePaths: data.paths.filter((value) => typeof value === 'string') } : {}),
+        ...(typeof data.activation === 'string' ? { activation: data.activation } : {}),
+        ...(typeof data.summary === 'string' ? { ruleSummary: data.summary } : {}),
+        ...(Object.keys(bound_to).length ? { bound_to } : {}),
+    };
+}
 /**
  * Extract @-mention references from content
  */
@@ -810,29 +836,100 @@ function resolveInstallRootHint() {
     catch { /* fall through */ }
     return '<aiwg install root>';
 }
+/** Shared serial/worker read, checksum and extraction. No index output or global reduction. */
+export function prepareIndexArtifact(job) {
+    const { fullPath, relativePath } = job;
+    const content = fs.readFileSync(fullPath, 'utf8');
+    const checksum = computeChecksum(content);
+    if (job.existingChecksum === checksum)
+        return { checksum };
+    const { data, body } = parseFrontmatter(content);
+    // YAML Flow documents (workflow.aiwg.io/v1) are pure YAML, not
+    // markdown+frontmatter — detect them up front so they classify and
+    // become discoverable (#1540).
+    const flow = parseFlowDoc(content, relativePath);
+    const decision = flow ? null : parseDecisionDoc(content, relativePath);
+    const gatePack = flow || decision ? null : parseGatePackDoc(content, relativePath);
+    const inferredType = inferType(data, relativePath);
+    const physicalType = inferType({ ...data, type: undefined }, relativePath);
+    const runbook = flow || decision || gatePack ? null : parseRunbookDoc(data, body, relativePath);
+    const schemaDoc = inferredType === 'schema' ? parseSchemaDoc(content, relativePath) : null;
+    const title = flow?.name ?? decision?.name ?? gatePack?.name ?? schemaDoc?.title ?? extractTitle(data, body);
+    const phase = typeof data.phase === 'string' ? data.phase : inferPhase(relativePath);
+    const type = flow?.type ?? decision?.type ?? gatePack?.type ?? (runbook ? 'runbook' : inferredType);
+    const tags = flow?.tags ?? decision?.tags ?? gatePack?.tags ?? (Array.isArray(data.tags) ? data.tags.map(String) : []);
+    const summary = flow?.description ?? decision?.description ?? gatePack?.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.
+    const isDiscoverable = OPERATIONAL_DISCOVERY_TYPES.includes(type);
+    // Declarative processes have no trigger phrases — they rely on their
+    // capability and structure-aware search terms.
+    const triggers = isDiscoverable && !flow ? extractTriggers(body, data) : undefined;
+    const capability = flow?.capability ?? decision?.capability ?? gatePack?.capability ?? schemaDoc?.capability ?? runbook?.capability ?? (isDiscoverable ? extractCapability(data, body) : undefined);
+    const kind = flow?.kind ?? decision?.kind ?? gatePack?.kind ?? runbook?.kind;
+    const sourceType = runbook && physicalType !== 'runbook' ? physicalType : undefined;
+    const searchTerms = flow?.searchTerms ?? decision?.searchTerms ?? gatePack?.searchTerms ?? schemaDoc?.searchTerms ?? runbook?.searchTerms;
+    const kernel = data.kernel === true || data.kernel === 'true' ? true : undefined;
+    // Script entrypoint metadata is meaningful for skills only (#1227).
+    const script = type === 'skill' ? extractSkillScript(data) : undefined;
+    const operationalState = normalizeOperationalState(data.operational_state);
+    const stateTransfer = normalizeStateTransferProjection(data.state_transfer);
+    // Canonical short name (#1233) — used by the scorer to floor exact-name
+    // queries to 1.0 so hyphenated kernel-skill names like `aiwg-doctor`
+    // remain searchable even when the rendered title strips the hyphen.
+    const name = flow?.name ?? decision?.name ?? gatePack?.name ?? schemaDoc?.name ?? (isDiscoverable ? extractCanonicalName(data, relativePath) : undefined);
+    const entry = {
+        path: relativePath,
+        type,
+        ...(kind ? { kind } : {}),
+        ...(sourceType ? { sourceType } : {}),
+        phase,
+        title,
+        tags,
+        created: typeof data.created === 'string' ? data.created : new Date(job.birthtimeMs).toISOString(),
+        updated: new Date(job.mtimeMs).toISOString(),
+        checksum,
+        summary,
+        dependencies,
+        ...(markdownLinks.length > 0 ? { markdownLinks } : {}),
+        dependents: [], // Computed after all entries are processed
+        ...(name ? { name } : {}),
+        ...(triggers && triggers.length > 0 ? { triggers } : {}),
+        ...(capability ? { capability } : {}),
+        ...(searchTerms && searchTerms.length > 0 ? { searchTerms } : {}),
+        ...(kernel ? { kernel } : {}),
+        ...(script ? { script } : {}),
+        ...(type === 'rule' || type === 'behavior' ? extractRuleBindings(data, body) :
+            Array.isArray(data.paths) ? { governedPaths: data.paths.filter((value) => typeof value === 'string') } : {}),
+        ...(operationalState ? { operationalState } : {}),
+        ...(stateTransfer ? { stateTransfer } : {}),
+    };
+    return { checksum, entry };
+}
 export async function buildIndex(cwd, options = {}) {
-    const { force = false, verbose = false, scope, outputDir, graph, explicit = true } = options;
+    const { force = false, verbose = false, scope, includeIgnored = false, outputDir, graph, explicit = true } = options;
+    const workers = resolveIndexWorkers(options.workers);
     const startTime = Date.now();
+    const log = options.quiet ? (..._args) => { } : console.log;
     // Ensure user-defined graphs are loaded
     loadUserGraphConfigs(cwd);
     loadGlobalGraphConfigs();
     // Determine scan directories based on graph type
     const graphConfig = graph ? GRAPH_CONFIGS[graph] : undefined;
     let scanDirs;
-    let fileExtensions;
     if (scope) {
         // Explicit scope overrides graph config
         scanDirs = [path.join(cwd, scope)];
-        fileExtensions = [...DEFAULT_INDEX_EXTENSIONS];
     }
     else if (graphConfig) {
         scanDirs = graphConfig.scanDirs.map(d => resolveGraphScanDir(cwd, d));
-        fileExtensions = graphConfig.extensions;
     }
     else {
         // Default: scan .aiwg/ (backward compatible)
         scanDirs = [resolveProjectAiwgDir(cwd)];
-        fileExtensions = [...DEFAULT_INDEX_EXTENSIONS];
     }
     // Verify at least one scan directory exists
     const existingDirs = scanDirs.filter(d => fs.existsSync(d));
@@ -851,16 +948,16 @@ export async function buildIndex(cwd, options = {}) {
         // required directories" sends the operator looking in the wrong place (#2530).
         if (graph === 'framework') {
             const installRoot = resolveInstallRootHint();
-            console.log('The framework graph indexes the AIWG corpus and can only be built at the');
-            console.log('install root, not in a consumer project. Build it there, then sync here:');
-            console.log('');
-            console.log(`  cd ${installRoot} && aiwg index build --graph framework --force`);
-            console.log(`  cd ${cwd} && aiwg index sync --backend fortemi-core --graph framework`);
-            console.log('');
-            console.log("As an immediate workaround, discovery also works with '--backend local'.");
+            log('The framework graph indexes the AIWG corpus and can only be built at the');
+            log('install root, not in a consumer project. Build it there, then sync here:');
+            log('');
+            log(`  cd ${installRoot} && aiwg index build --graph framework --force`);
+            log(`  cd ${cwd} && aiwg index sync --backend fortemi-core --graph framework`);
+            log('');
+            log("As an immediate workaround, discovery also works with '--backend local'.");
         }
         else {
-            console.log('Run this command from a project with the required directories.');
+            log('Run this command from a project with the required directories.');
         }
         process.exit(1);
     }
@@ -890,24 +987,21 @@ export async function buildIndex(cwd, options = {}) {
             verbose,
         });
         const buildTimeMs = Date.now() - startTime;
-        console.log(`Source graph built in ${buildTimeMs}ms`);
-        console.log(`  Output: ${INDEX_DIR}/source/`);
+        log(`Source graph built in ${buildTimeMs}ms`);
+        log(`  Output: ${INDEX_DIR}/source/`);
         return;
     }
     // Load existing index for incremental updates
-    const existingIndex = force
-        ? null
-        : outputDir
-            ? loadIndexFromDir(indexOutputDir, 'metadata.json')
-            : loadGraphIndexFile(effectiveOutputCwd, 'metadata.json', graph);
-    const canReuseExisting = existingIndex?.version === INDEX_VERSION
-        && existingIndex.extractorVersion === INDEX_EXTRACTOR_VERSION;
-    const existingEntries = canReuseExisting ? existingIndex.entries : {};
-    // Load checksum manifest for fast stat-based change detection (#794).
-    // When --force is set we skip the manifest entirely and rebuild everything.
-    const manifest = force || !canReuseExisting
+    const backendType = resolveGraphBackendType(graph);
+    const buildConfigHash = createHash('sha256')
+        .update(JSON.stringify({ graphConfig, backendType }))
+        .digest('hex');
+    const storedManifest = force
         ? { version: 1, generated: '', entries: {} }
         : loadManifest(indexOutputDir);
+    const useFilenameMetadata = graphConfig?.nodeStrategy === 'filename-metadata';
+    const reusable = !useFilenameMetadata && !graphConfig?.metadataSupplements?.length && !graphConfig?.edgeExtraction;
+    const fileStats = !force && reusable ? new Map() : undefined;
     const nextManifestEntries = {};
     const manifestStats = {
         checked: 0,
@@ -917,16 +1011,117 @@ export async function buildIndex(cwd, options = {}) {
         pruned: 0,
     };
     // Collect files from all scan directories
-    const files = scope
-        ? existingDirs.flatMap(dir => findArtifactFiles(dir, fileExtensions))
-        : await collectGraphIndexFiles(cwd, graph);
+    const files = await collectGraphIndexFiles(cwd, graph, { scope, includeIgnored, fileStats });
     const entries = {};
     const tagIndex = {};
     const depGraph = {};
     let newCount = 0;
     let updatedCount = 0;
     let unchangedCount = 0;
-    const useFilenameMetadata = graphConfig?.nodeStrategy === 'filename-metadata';
+    const reportBuild = (buildTimeMs, total) => {
+        log(`Artifact index built in ${buildTimeMs}ms`);
+        log(`  Indexed ${newCount} new, updated ${updatedCount}, unchanged ${unchangedCount}`);
+        log(`  Total: ${total} artifacts`);
+        if (!force && manifestStats.checked > 0) {
+            const fastPath = manifestStats.statSkipped;
+            const slowPath = manifestStats.checked - manifestStats.statSkipped;
+            log(`  Change detection: ${manifestStats.checked} checked, ${fastPath} skipped via stat, ${slowPath} content-read, ${manifestStats.reindexed} re-indexed`);
+            if (manifestStats.pruned > 0) {
+                log(`  Pruned ${manifestStats.pruned} stale manifest entries (files no longer on disk)`);
+            }
+        }
+        const displayDir = graph ? indexOutputDir : `${INDEX_DIR}/`;
+        log(`  Output: ${displayDir}`);
+    };
+    const requiredFiles = ['tags.json', 'dependencies.json'];
+    if (backendType === 'sqlite')
+        requiredFiles.push('graph.db');
+    const fileSignature = (filename) => {
+        try {
+            const stat = fs.statSync(path.join(indexOutputDir, filename), { bigint: true });
+            return [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].join(':');
+        }
+        catch {
+            return '';
+        }
+    };
+    const relationsReceiptMatches = () => {
+        const projection = storedManifest.receipt?.relations;
+        return graph !== 'framework' || Boolean(projection?.revision === FRAMEWORK_RELATIONS_REVISION
+            && projection.signature && projection.signature === fileSignature('relations.json'));
+    };
+    const entriesDigest = (values) => createHash('sha256').update(JSON.stringify(values)).digest('hex');
+    const writeBuildManifest = (values) => {
+        writeManifest(indexOutputDir, { version: 1, generated: new Date().toISOString(), entries: values,
+            ...(reusable ? { receipt: {
+                    indexVersion: INDEX_VERSION, extractorVersion: INDEX_EXTRACTOR_VERSION, buildConfigHash,
+                    sourceRoot: path.resolve(cwd), metadataSignature: fileSignature('metadata.json'), entriesDigest: entriesDigest(values),
+                    ...(graph === 'framework' ? { relations: { revision: FRAMEWORK_RELATIONS_REVISION, signature: fileSignature('relations.json') } } : {}),
+                } } : {}),
+        });
+    };
+    // A successful receipt proves the manifest belongs to this exact metadata
+    // file. Still enumerate/stat every source and verify the complete file set;
+    // unchanged builds need not parse the much larger metadata/dependency data.
+    const receipt = storedManifest.receipt;
+    if (!force && reusable && storedManifest.generated && receipt
+        && receipt.indexVersion === INDEX_VERSION && receipt.extractorVersion === INDEX_EXTRACTOR_VERSION
+        && receipt.buildConfigHash === buildConfigHash && receipt.sourceRoot === path.resolve(cwd)
+        && receipt.metadataSignature && receipt.metadataSignature === fileSignature('metadata.json')
+        && relationsReceiptMatches()
+        && receipt.entriesDigest === entriesDigest(storedManifest.entries)
+        && files.length === Object.keys(storedManifest.entries).length
+        && requiredFiles.every(filename => fs.existsSync(path.join(indexOutputDir, filename)))) {
+        const stats = loadIndexFromDir(indexOutputDir, 'stats.json');
+        if (stats?.version === INDEX_VERSION && stats.extractorVersion === INDEX_EXTRACTOR_VERSION
+            && stats.totalArtifacts === files.length && files.every(file => {
+            try {
+                return statMatches(fileStats?.get(file) ?? fs.statSync(file), storedManifest.entries[indexPathFor(cwd, file, graph)]);
+            }
+            catch {
+                return false;
+            }
+        })) {
+            unchangedCount = files.length;
+            manifestStats.checked = files.length;
+            manifestStats.statSkipped = files.length;
+            const buildTimeMs = Date.now() - startTime;
+            writeIndexFile(effectiveOutputCwd, 'stats.json', { ...stats, builtAt: new Date().toISOString(), buildTimeMs }, indexOutputDir);
+            reportBuild(buildTimeMs, files.length);
+            return;
+        }
+    }
+    const existingIndex = force ? null : outputDir
+        ? loadIndexFromDir(indexOutputDir, 'metadata.json')
+        : loadGraphIndexFile(effectiveOutputCwd, 'metadata.json', graph);
+    const canReuseExisting = existingIndex?.version === INDEX_VERSION
+        && existingIndex.extractorVersion === INDEX_EXTRACTOR_VERSION && existingIndex.buildConfigHash === buildConfigHash;
+    const existingEntries = canReuseExisting ? existingIndex.entries : {};
+    const manifest = canReuseExisting ? storedManifest : { version: 1, generated: '', entries: {} };
+    // Establish the complete changed-file batch before any extraction/reduction.
+    // Warm stat hits never create threads or read source contents.
+    const preparationStats = new Map();
+    const jobs = [];
+    if (!useFilenameMetadata)
+        for (const fullPath of files) {
+            let stat;
+            try {
+                stat = fileStats?.get(fullPath) ?? fs.statSync(fullPath);
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    continue;
+                throw error;
+            }
+            preparationStats.set(fullPath, stat);
+            const relativePath = indexPathFor(cwd, fullPath, graph), previous = manifest.entries[relativePath];
+            if (!force && statMatches(stat, previous) && existingEntries[relativePath]?.checksum === previous?.checksum)
+                continue;
+            jobs.push({ fullPath, relativePath, mtimeMs: stat.mtimeMs, birthtimeMs: stat.birthtimeMs, sizeBytes: stat.size,
+                ...(!force && existingEntries[relativePath] ? { existingChecksum: existingEntries[relativePath].checksum } : {}) });
+        }
+    const preparation = await runIndexPreparation(jobs, prepareIndexArtifact, import.meta.url, workers, options.onDiagnostic ?? (message => console.warn(`Index preparation: ${message}`)));
+    const preparedArtifacts = new Map(jobs.map((job, index) => [job.fullPath, preparation.results[index]]));
     for (const fullPath of files) {
         const relativePath = indexPathFor(cwd, fullPath, graph);
         let entry;
@@ -944,7 +1139,7 @@ export async function buildIndex(cwd, options = {}) {
                 entries[relativePath] = existingEntries[relativePath];
                 unchangedCount++;
                 if (verbose)
-                    console.log(`  unchanged: ${relativePath}`);
+                    log(`  unchanged: ${relativePath}`);
                 continue;
             }
             entry = buildFilenameMetadataEntry(relativePath, fullPath, graphConfig?.filenamePattern);
@@ -956,13 +1151,13 @@ export async function buildIndex(cwd, options = {}) {
             // This is the fast path: unchanged files don't touch the filesystem beyond fs.statSync.
             let stat;
             try {
-                stat = fs.statSync(fullPath);
+                stat = preparationStats.get(fullPath) ?? fs.statSync(fullPath);
             }
             catch (err) {
                 if (err.code === 'ENOENT') {
                     manifestStats.pruned++;
                     if (verbose)
-                        console.log(`  skipped missing: ${relativePath}`);
+                        log(`  skipped missing: ${relativePath}`);
                     continue;
                 }
                 throw err;
@@ -976,98 +1171,70 @@ export async function buildIndex(cwd, options = {}) {
                 unchangedCount++;
                 manifestStats.statSkipped++;
                 if (verbose)
-                    console.log(`  unchanged (stat): ${relativePath}`);
+                    log(`  unchanged (stat): ${relativePath}`);
                 continue;
             }
-            // Phase 2: content read + checksum verification for files that looked changed.
-            const content = fs.readFileSync(fullPath, 'utf-8');
-            const checksum = computeChecksum(content);
-            // Skip unchanged files in incremental mode (checksum matched despite stat drift)
+            const prepared = preparedArtifacts.get(fullPath);
+            const { checksum } = prepared;
             if (!force && existingEntries[relativePath]?.checksum === checksum) {
                 entries[relativePath] = existingEntries[relativePath];
-                // Update manifest with current stat so Phase 1 succeeds next time.
                 nextManifestEntries[relativePath] = makeEntry(checksum, stat);
                 unchangedCount++;
                 manifestStats.checksumSkipped++;
                 if (verbose)
-                    console.log(`  unchanged (checksum): ${relativePath}`);
+                    log(`  unchanged (checksum): ${relativePath}`);
                 continue;
             }
             manifestStats.reindexed++;
             nextManifestEntries[relativePath] = makeEntry(checksum, stat);
-            const { data, body } = parseFrontmatter(content);
-            // YAML Flow documents (workflow.aiwg.io/v1) are pure YAML, not
-            // markdown+frontmatter — detect them up front so they classify and
-            // become discoverable (#1540).
-            const flow = parseFlowDoc(content, relativePath);
-            const decision = flow ? null : parseDecisionDoc(content, relativePath);
-            const gatePack = flow || decision ? null : parseGatePackDoc(content, relativePath);
-            const inferredType = inferType(data, relativePath);
-            const physicalType = inferType({ ...data, type: undefined }, relativePath);
-            const runbook = flow || decision || gatePack ? null : parseRunbookDoc(data, body, relativePath);
-            const schemaDoc = inferredType === 'schema' ? parseSchemaDoc(content, relativePath) : null;
-            const title = flow?.name ?? decision?.name ?? gatePack?.name ?? schemaDoc?.title ?? extractTitle(data, body);
-            const phase = typeof data.phase === 'string' ? data.phase : inferPhase(relativePath);
-            const type = flow?.type ?? decision?.type ?? gatePack?.type ?? (runbook ? 'runbook' : inferredType);
-            const tags = flow?.tags ?? decision?.tags ?? gatePack?.tags ?? (Array.isArray(data.tags) ? data.tags.map(String) : []);
-            const summary = flow?.description ?? decision?.description ?? gatePack?.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.
-            const isDiscoverable = OPERATIONAL_DISCOVERY_TYPES.includes(type);
-            // Declarative processes have no trigger phrases — they rely on their
-            // capability and structure-aware search terms.
-            const triggers = isDiscoverable && !flow ? extractTriggers(body, data) : undefined;
-            const capability = flow?.capability ?? decision?.capability ?? gatePack?.capability ?? schemaDoc?.capability ?? runbook?.capability ?? (isDiscoverable ? extractCapability(data, body) : undefined);
-            const kind = flow?.kind ?? decision?.kind ?? gatePack?.kind ?? runbook?.kind;
-            const sourceType = runbook && physicalType !== 'runbook' ? physicalType : undefined;
-            const searchTerms = flow?.searchTerms ?? decision?.searchTerms ?? gatePack?.searchTerms ?? schemaDoc?.searchTerms ?? runbook?.searchTerms;
-            const kernel = data.kernel === true || data.kernel === 'true' ? true : undefined;
-            // Script entrypoint metadata is meaningful for skills only (#1227).
-            const script = type === 'skill' ? extractSkillScript(data) : undefined;
-            const operationalState = normalizeOperationalState(data.operational_state);
-            const stateTransfer = normalizeStateTransferProjection(data.state_transfer);
-            // Canonical short name (#1233) — used by the scorer to floor exact-name
-            // queries to 1.0 so hyphenated kernel-skill names like `aiwg-doctor`
-            // remain searchable even when the rendered title strips the hyphen.
-            const name = flow?.name ?? decision?.name ?? gatePack?.name ?? schemaDoc?.name ?? (isDiscoverable ? extractCanonicalName(data, relativePath) : undefined);
-            entry = {
-                path: relativePath,
-                type,
-                ...(kind ? { kind } : {}),
-                ...(sourceType ? { sourceType } : {}),
-                phase,
-                title,
-                tags,
-                created: typeof data.created === 'string' ? data.created : stat.birthtime.toISOString(),
-                updated: stat.mtime.toISOString(),
-                checksum,
-                summary,
-                dependencies,
-                ...(markdownLinks.length > 0 ? { markdownLinks } : {}),
-                dependents: [], // Computed after all entries are processed
-                ...(name ? { name } : {}),
-                ...(triggers && triggers.length > 0 ? { triggers } : {}),
-                ...(capability ? { capability } : {}),
-                ...(searchTerms && searchTerms.length > 0 ? { searchTerms } : {}),
-                ...(kernel ? { kernel } : {}),
-                ...(script ? { script } : {}),
-                ...(operationalState ? { operationalState } : {}),
-                ...(stateTransfer ? { stateTransfer } : {}),
-            };
+            entry = prepared.entry;
         }
         entries[relativePath] = entry;
         if (existingEntries[relativePath]) {
             updatedCount++;
             if (verbose)
-                console.log(`  updated: ${relativePath}`);
+                log(`  updated: ${relativePath}`);
         }
         else {
             newCount++;
             if (verbose)
-                console.log(`  new: ${relativePath}`);
+                log(`  new: ${relativePath}`);
+        }
+    }
+    // Reuse derived indexes only when their complete input set is unchanged.
+    // Supplements can live outside the scanned files, so they must still be read.
+    // Configured edge extractors must run to discard stale cached edges even
+    // when source checksums match.
+    const total = Object.keys(entries).length;
+    if (canReuseExisting && !useFilenameMetadata && !graphConfig?.metadataSupplements?.length
+        && !graphConfig?.edgeExtraction
+        && newCount === 0 && updatedCount === 0
+        && total === Object.keys(existingEntries).length
+        && manifest.generated && total === Object.keys(manifest.entries).length
+        && manifestStats.pruned === 0) {
+        const stats = loadIndexFromDir(indexOutputDir, 'stats.json');
+        if (stats?.version === INDEX_VERSION && stats.extractorVersion === INDEX_EXTRACTOR_VERSION
+            && stats.totalArtifacts === total
+            && requiredFiles.every(filename => fs.existsSync(path.join(indexOutputDir, filename)))) {
+            // A timestamp-only source change needs a manifest refresh, but does not
+            // invalidate metadata, tags, dependencies, or the persistent backend.
+            const projectionNeedsRepair = graph === 'framework' && !relationsReceiptMatches();
+            if (graph === 'framework') {
+                const { writeRelations } = await import('./relations-builder.js');
+                await writeRelations(entries, effectiveOutputCwd, indexOutputDir, force || !relationsReceiptMatches());
+            }
+            const buildTimeMs = Date.now() - startTime;
+            writeIndexFile(effectiveOutputCwd, 'stats.json', {
+                ...stats,
+                builtAt: new Date().toISOString(),
+                buildTimeMs,
+            }, indexOutputDir);
+            // Preserve no-op manifest bytes after output-only timestamp drift.
+            // Renew receipts only for changed source stats or repaired projections.
+            if (manifestStats.checksumSkipped > 0 || projectionNeedsRepair)
+                writeBuildManifest(nextManifestEntries);
+            reportBuild(buildTimeMs, total);
+            return;
         }
     }
     // Apply metadata supplements if configured (enriches filename-metadata nodes from sidecars)
@@ -1084,13 +1251,18 @@ export async function buildIndex(cwd, options = {}) {
     }
     // Build dependency graph and compute dependents
     let markdownLinkEdgeCount = 0;
+    const entryPaths = Object.keys(entries);
+    const dependencyPaths = new Map();
     for (const entry of Object.values(entries)) {
         if (!depGraph[entry.path]) {
             depGraph[entry.path] = { upstream: [], downstream: [] };
         }
         for (const dep of entry.dependencies) {
             // Normalize: check if referenced path exists in the index
-            const normalizedDep = Object.keys(entries).find(p => p === dep || p.endsWith(dep));
+            if (!dependencyPaths.has(dep)) {
+                dependencyPaths.set(dep, entryPaths.find(p => p === dep || p.endsWith(dep)));
+            }
+            const normalizedDep = dependencyPaths.get(dep);
             if (normalizedDep && normalizedDep !== entry.path) {
                 addDependencyEdge(depGraph, entries, entry.path, normalizedDep, 'depends-on');
             }
@@ -1173,18 +1345,23 @@ export async function buildIndex(cwd, options = {}) {
                 .filter(edge => !canonicalOutgoing.has(edge)).length,
         };
         if (verbose && citationEdgeCount > 0) {
-            console.log(`  citation edges: ${citationEdgeCount}`);
+            log(`  citation edges: ${citationEdgeCount}`);
         }
     }
     // Deduplicate dependents
     for (const entry of Object.values(entries)) {
         entry.dependents = [...new Set(entry.dependents)];
     }
+    if (graph === 'framework') {
+        const { writeRelations } = await import('./relations-builder.js');
+        await writeRelations(entries, effectiveOutputCwd, indexOutputDir, force || !relationsReceiptMatches());
+    }
     const buildTimeMs = Date.now() - startTime;
     // Write index files
     const index = {
         version: INDEX_VERSION,
         extractorVersion: INDEX_EXTRACTOR_VERSION,
+        buildConfigHash,
         builtAt: new Date().toISOString(),
         buildTimeMs,
         entries,
@@ -1195,8 +1372,6 @@ export async function buildIndex(cwd, options = {}) {
     // Materialize the configured backend and always retain dependencies.json as
     // the stable compatibility/export contract.
     const { createGraphBackend } = await import('./graph-backend.js');
-    const { resolveGraphBackendType } = await import('./types.js');
-    const backendType = resolveGraphBackendType(graph);
     const persistentPath = backendType === 'sqlite' ? path.join(indexOutputDir, 'graph.db') : undefined;
     let selectedBackend;
     try {
@@ -1210,15 +1385,9 @@ export async function buildIndex(cwd, options = {}) {
     // The next manifest contains entries for every file we processed this build.
     // Files that disappeared from disk are pruned; the resulting manifest is
     // written atomically.
-    const nextManifest = {
-        version: 1,
-        generated: new Date().toISOString(),
-        entries: nextManifestEntries,
-    };
     manifestStats.pruned = Object.keys(manifest.entries).length - Object.keys(nextManifestEntries).length;
     if (manifestStats.pruned < 0)
         manifestStats.pruned = 0;
-    writeManifest(indexOutputDir, nextManifest);
     // Write stats
     const downstreamEdges = Object.values(depGraph).reduce((sum, node) => sum + node.downstream.length, 0);
     const adjacencyEntries = Object.values(depGraph).reduce((sum, node) => sum + node.upstream.length + node.downstream.length, 0);
@@ -1262,22 +1431,8 @@ export async function buildIndex(cwd, options = {}) {
             mostReferenced,
         },
     }, indexOutputDir);
+    writeBuildManifest(nextManifestEntries);
     // Report
-    const total = Object.keys(entries).length;
-    console.log(`Artifact index built in ${buildTimeMs}ms`);
-    console.log(`  Indexed ${newCount} new, updated ${updatedCount}, unchanged ${unchangedCount}`);
-    console.log(`  Total: ${total} artifacts`);
-    // Report manifest-driven change detection stats (only meaningful when !force
-    // and we actually went through the content-read path for at least one file)
-    if (!force && manifestStats.checked > 0) {
-        const fastPath = manifestStats.statSkipped;
-        const slowPath = manifestStats.checked - manifestStats.statSkipped;
-        console.log(`  Change detection: ${manifestStats.checked} checked, ${fastPath} skipped via stat, ${slowPath} content-read, ${manifestStats.reindexed} re-indexed`);
-        if (manifestStats.pruned > 0) {
-            console.log(`  Pruned ${manifestStats.pruned} stale manifest entries (files no longer on disk)`);
-        }
-    }
-    const displayDir = graph ? indexOutputDir : `${INDEX_DIR}/`;
-    console.log(`  Output: ${displayDir}`);
+    reportBuild(buildTimeMs, total);
 }
 //# sourceMappingURL=index-builder.js.map