@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.17

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

@@ -0,0 +1,354 @@
+/**
+ * Semantic Embedding Index
+ *
+ * Optional ANN (approximate nearest neighbor) layer on top of the artifact
+ * index. Embeds node summaries/titles, or opt-in chunked source bodies, into
+ * dense vectors using a small local model and stores them in an HNSW index for
+ * fast similarity queries.
+ *
+ * Install: npm install @xenova/transformers hnswlib-node
+ *
+ * @implements #730
+ * @source @src/artifacts/types.ts
+ * @tests @test/unit/artifacts/embedding-index.test.ts
+ */
+import fs from 'fs';
+import path from 'path';
+/**
+ * Default embedding model (all-MiniLM-L6-v2: ~22MB, 384 dims, ~5ms/embedding on CPU)
+ */
+export const DEFAULT_EMBEDDING_MODEL = 'Xenova/all-MiniLM-L6-v2';
+export const DEFAULT_EMBEDDING_DIMS = 384;
+const DEFAULT_MAX_EMBEDDING_BODY_BYTES = 256 * 1024;
+const DEFAULT_BODY_CHUNK_CHARS = 1400;
+const DEFAULT_BODY_CHUNK_OVERLAP_CHARS = 200;
+const DEFAULT_MAX_BODY_CHUNKS = 48;
+const BINARY_SOURCE_EXTENSIONS = new Set([
+    '.7z', '.a', '.avi', '.bin', '.bmp', '.bz2', '.class', '.dll', '.doc',
+    '.docx', '.dylib', '.exe', '.gif', '.gz', '.ico', '.jar', '.jpeg', '.jpg',
+    '.mov', '.mp3', '.mp4', '.o', '.odt', '.pdf', '.png', '.ppt', '.pptx',
+    '.so', '.tar', '.tgz', '.war', '.webp', '.xls', '.xlsx', '.zip',
+]);
+function stripFrontmatter(text) {
+    if (!text.startsWith('---'))
+        return text;
+    const match = text.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
+    return match ? text.slice(match[0].length) : text;
+}
+function looksBinary(buffer) {
+    if (buffer.includes(0))
+        return true;
+    const sample = buffer.subarray(0, Math.min(buffer.length, 4096)).toString('utf-8');
+    if (sample.length === 0)
+        return false;
+    const replacementCount = (sample.match(/\uFFFD/g) ?? []).length;
+    return replacementCount / sample.length > 0.01;
+}
+function metadataTextForEntry(entry) {
+    return [
+        `title: ${entry.title}`,
+        entry.name ? `name: ${entry.name}` : '',
+        `type: ${entry.type}`,
+        entry.kind ? `kind: ${entry.kind}` : '',
+        entry.sourceType ? `source type: ${entry.sourceType}` : '',
+        entry.capability ? `capability: ${entry.capability}` : '',
+        entry.summary ? `summary: ${entry.summary}` : '',
+        entry.tags.length > 0 ? `tags: ${entry.tags.join(', ')}` : '',
+        entry.triggers?.length ? `triggers: ${entry.triggers.join('; ')}` : '',
+        entry.searchTerms?.length ? `search terms: ${entry.searchTerms.join('; ')}` : '',
+    ].filter(Boolean).join('\n');
+}
+function chunkText(text, chunkChars, overlapChars, maxChunks) {
+    const normalized = text.replace(/\s+/g, ' ').trim();
+    if (!normalized)
+        return [];
+    const size = Math.max(200, chunkChars);
+    const overlap = Math.max(0, Math.min(overlapChars, size - 1));
+    const chunks = [];
+    let start = 0;
+    while (start < normalized.length && chunks.length < maxChunks) {
+        let end = Math.min(start + size, normalized.length);
+        if (end < normalized.length) {
+            const boundary = normalized.lastIndexOf(' ', end);
+            if (boundary > start + Math.floor(size * 0.6))
+                end = boundary;
+        }
+        chunks.push(normalized.slice(start, end).trim());
+        if (end >= normalized.length)
+            break;
+        start = Math.max(end - overlap, start + 1);
+    }
+    return chunks.filter(Boolean);
+}
+function sourceBodyForEntry(cwd, entry, maxBytes) {
+    const sourcePath = path.isAbsolute(entry.path) ? entry.path : path.join(cwd, entry.path);
+    try {
+        const stat = fs.statSync(sourcePath);
+        if (!stat.isFile() || stat.size > maxBytes)
+            return '';
+        if (BINARY_SOURCE_EXTENSIONS.has(path.extname(sourcePath).toLowerCase()))
+            return '';
+        const buffer = fs.readFileSync(sourcePath);
+        if (looksBinary(buffer))
+            return '';
+        return stripFrontmatter(buffer.toString('utf-8')).trim();
+    }
+    catch {
+        return '';
+    }
+}
+export function embeddingTextForEntry(entry, options = {}) {
+    return embeddingTextsForEntry(entry, options).join('\n\n');
+}
+export function embeddingTextsForEntry(entry, options = {}) {
+    const metadataText = metadataTextForEntry(entry);
+    if (options.granularity !== 'body')
+        return [metadataText];
+    const bodyText = options.cwd
+        ? sourceBodyForEntry(options.cwd, entry, options.maxSourceBodyBytes ?? DEFAULT_MAX_EMBEDDING_BODY_BYTES)
+        : '';
+    if (!bodyText)
+        return [metadataText];
+    const chunks = chunkText(bodyText, options.bodyChunkChars ?? DEFAULT_BODY_CHUNK_CHARS, options.bodyChunkOverlapChars ?? DEFAULT_BODY_CHUNK_OVERLAP_CHARS, options.maxBodyChunks ?? DEFAULT_MAX_BODY_CHUNKS);
+    return chunks.length > 0 ? chunks.map(chunk => [metadataText, chunk].join('\n\n')) : [metadataText];
+}
+function normalizeVector(vector) {
+    const norm = Math.sqrt(vector.reduce((sum, value) => sum + value * value, 0));
+    if (norm === 0)
+        return vector;
+    return vector.map(value => value / norm);
+}
+async function embedEntryVector(embed, entry, options) {
+    const texts = embeddingTextsForEntry(entry, options);
+    const vectors = [];
+    for (const text of texts) {
+        const result = await embed(text, { pooling: 'mean', normalize: true });
+        vectors.push(Array.from(result.data));
+    }
+    if (vectors.length === 1)
+        return vectors[0];
+    const mean = new Array(vectors[0].length).fill(0);
+    for (const vector of vectors) {
+        for (let i = 0; i < vector.length; i++) {
+            mean[i] += vector[i];
+        }
+    }
+    return normalizeVector(mean.map(value => value / vectors.length));
+}
+/**
+ * Check if embedding dependencies are available.
+ */
+export async function checkEmbeddingDeps() {
+    const missing = [];
+    try {
+        await (new Function('m', 'return import(m)'))('@xenova/transformers');
+    }
+    catch {
+        missing.push('@xenova/transformers');
+    }
+    try {
+        await (new Function('m', 'return import(m)'))('hnswlib-node');
+    }
+    catch {
+        missing.push('hnswlib-node');
+    }
+    return { available: missing.length === 0, missing };
+}
+/**
+ * Build an embedding index from artifact metadata entries.
+ *
+ * Embeds each entry into a dense vector and stores it in an HNSW index for
+ * fast approximate nearest-neighbor queries. Body granularity reads the source
+ * file, strips frontmatter, embeds bounded overlapping chunks, and stores the
+ * normalized mean vector for the node.
+ *
+ * @param entries - Map of node ID → MetadataEntry
+ * @param outputDir - Directory to write embeddings/ subfolder
+ * @param model - Transformer model identifier
+ * @returns Number of entries embedded
+ */
+export async function buildEmbeddingIndex(entries, outputDir, model = DEFAULT_EMBEDDING_MODEL, options = {}) {
+    const transformersMod = await (new Function('m', 'return import(m)'))('@xenova/transformers');
+    const { pipeline } = transformersMod;
+    const hnswlib = await (new Function('m', 'return import(m)'))('hnswlib-node');
+    const HierarchicalNSW = hnswlib.HierarchicalNSW ?? hnswlib.default?.HierarchicalNSW;
+    if (!HierarchicalNSW) {
+        throw new Error('hnswlib-node: HierarchicalNSW not found in module exports');
+    }
+    const embed = await pipeline('feature-extraction', model);
+    const ids = Object.keys(entries);
+    if (ids.length === 0)
+        return 0;
+    // Determine dimensions from a test embedding
+    const testResult = await embed('test', { pooling: 'mean', normalize: true });
+    const dims = testResult.data.length;
+    const index = new HierarchicalNSW('cosine', dims);
+    index.initIndex(Math.max(ids.length, 1));
+    const checksums = {};
+    for (let i = 0; i < ids.length; i++) {
+        const entry = entries[ids[i]];
+        const vector = await embedEntryVector(embed, entry, options);
+        index.addPoint(vector, i);
+        checksums[ids[i]] = entry.checksum;
+    }
+    // Write index and manifest
+    const embeddingsDir = path.join(outputDir, 'embeddings');
+    fs.mkdirSync(embeddingsDir, { recursive: true });
+    index.writeIndex(path.join(embeddingsDir, 'vectors.hnsw'));
+    const manifest = {
+        model,
+        dims,
+        nodeIds: ids,
+        builtAt: new Date().toISOString(),
+        checksums,
+        granularity: options.granularity === 'body' ? 'body' : 'title-summary',
+    };
+    fs.writeFileSync(path.join(embeddingsDir, 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf-8');
+    return ids.length;
+}
+/**
+ * Load an embedding manifest from an index directory.
+ */
+export function loadEmbeddingManifest(indexDir) {
+    const manifestPath = path.join(indexDir, 'embeddings', 'manifest.json');
+    if (!fs.existsSync(manifestPath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Query the embedding index for semantically similar artifacts.
+ *
+ * @param query - Natural language query string
+ * @param indexDir - Directory containing the embeddings/ subfolder
+ * @param topK - Number of results to return
+ * @returns Ranked list of semantic results
+ */
+export async function semanticQuery(query, indexDir, topK = 10) {
+    const manifest = loadEmbeddingManifest(indexDir);
+    if (!manifest) {
+        throw new Error(`No embedding index found at ${indexDir}/embeddings/`);
+    }
+    const transformersMod = await (new Function('m', 'return import(m)'))('@xenova/transformers');
+    const { pipeline } = transformersMod;
+    const hnswlib = await (new Function('m', 'return import(m)'))('hnswlib-node');
+    const HierarchicalNSW = hnswlib.HierarchicalNSW ?? hnswlib.default?.HierarchicalNSW;
+    if (!HierarchicalNSW) {
+        throw new Error('hnswlib-node: HierarchicalNSW not found in module exports');
+    }
+    const embed = await pipeline('feature-extraction', manifest.model);
+    const result = await embed(query, { pooling: 'mean', normalize: true });
+    const index = new HierarchicalNSW('cosine', manifest.dims);
+    // readIndexSync, not the async readIndex — the async form returns a promise
+    // that, if not awaited, leaves the index empty (getCurrentCount() === 0).
+    index.readIndexSync(path.join(indexDir, 'embeddings', 'vectors.hnsw'));
+    // setEfSearch controls recall quality — higher = better but slower
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const idx = index;
+    if (typeof idx.setEfSearch === 'function') {
+        idx.setEfSearch(Math.max(topK * 2, 50));
+    }
+    const effectiveK = Math.min(topK, manifest.nodeIds.length);
+    const { neighbors, distances } = index.searchKnn(Array.from(result.data), effectiveK);
+    return neighbors.map((pos, i) => ({
+        nodeId: manifest.nodeIds[pos],
+        // HNSW cosine distance is 1 - cosine_similarity
+        score: 1 - (distances[i] ?? 0),
+    }));
+}
+/**
+ * Get semantic neighbors of a specific node.
+ *
+ * @param nodeId - Node to find neighbors for
+ * @param entries - Metadata entries to get the node's text
+ * @param indexDir - Directory containing the embeddings/ subfolder
+ * @param topK - Number of results
+ */
+export async function semanticNeighbors(nodeId, entries, indexDir, topK = 10) {
+    const entry = entries[nodeId];
+    if (!entry) {
+        throw new Error(`Node '${nodeId}' not found in metadata`);
+    }
+    const queryText = `${entry.title} ${entry.summary}`.trim();
+    // Get topK + 1 since the node itself will likely be the top result
+    const results = await semanticQuery(queryText, indexDir, topK + 1);
+    // Filter out the query node itself
+    return results.filter(r => r.nodeId !== nodeId).slice(0, topK);
+}
+/**
+ * Determine which entries need re-embedding based on checksum changes.
+ *
+ * @param entries - Current metadata entries
+ * @param manifest - Existing embedding manifest
+ * @returns Object with entries that changed and entries that are new
+ */
+export function detectEmbeddingChanges(entries, manifest) {
+    const changed = [];
+    const added = [];
+    const removed = [];
+    const manifestIds = new Set(manifest.nodeIds);
+    const entryIds = new Set(Object.keys(entries));
+    for (const id of entryIds) {
+        if (!manifestIds.has(id)) {
+            added.push(id);
+        }
+        else if (entries[id].checksum !== manifest.checksums[id]) {
+            changed.push(id);
+        }
+    }
+    for (const id of manifestIds) {
+        if (!entryIds.has(id)) {
+            removed.push(id);
+        }
+    }
+    return { changed, added, removed };
+}
+/**
+ * Near-duplicate report (#1493). Reads the prebuilt embedding index and, using
+ * each stored vector (no re-embedding), finds node pairs whose cosine
+ * similarity is at or above `threshold`. Pairs are de-duplicated (unordered)
+ * and returned most-similar-first.
+ *
+ * Requires a built embedding index (`aiwg index embed`). Throws if absent.
+ */
+export async function dedupReport(indexDir, threshold = 0.92, topK = 5) {
+    const manifest = loadEmbeddingManifest(indexDir);
+    if (!manifest) {
+        throw new Error(`No embedding index found at ${indexDir}/embeddings/`);
+    }
+    const hnswlib = await (new Function('m', 'return import(m)'))('hnswlib-node');
+    const HierarchicalNSW = hnswlib.HierarchicalNSW ?? hnswlib.default?.HierarchicalNSW;
+    if (!HierarchicalNSW) {
+        throw new Error('hnswlib-node: HierarchicalNSW not found in module exports');
+    }
+    const index = new HierarchicalNSW('cosine', manifest.dims);
+    index.readIndexSync(path.join(indexDir, 'embeddings', 'vectors.hnsw'));
+    const idx = index;
+    const k = Math.min(topK + 1, manifest.nodeIds.length);
+    if (typeof idx.setEf === 'function')
+        idx.setEf(Math.max(k * 2, 50));
+    const seen = new Map();
+    for (let i = 0; i < manifest.nodeIds.length; i++) {
+        const vec = idx.getPoint(i);
+        const { neighbors, distances } = index.searchKnn(vec, k);
+        for (let n = 0; n < neighbors.length; n++) {
+            const j = neighbors[n];
+            if (j === i)
+                continue;
+            const score = 1 - (distances[n] ?? 0);
+            if (score < threshold)
+                continue;
+            const [a, b] = [manifest.nodeIds[i], manifest.nodeIds[j]].sort();
+            const key = `${a}|${b}`;
+            const prev = seen.get(key);
+            if (!prev || score > prev.score)
+                seen.set(key, { a, b, score });
+        }
+    }
+    return [...seen.values()].sort((x, y) => y.score - x.score);
+}
+//# sourceMappingURL=embedding-index.js.map

package/dist/src/artifacts/enrichment/cli.js

@@ -0,0 +1,240 @@
+/**
+ * `aiwg index enrich` subcommand router.
+ *
+ * Subcommands / flags:
+ *   --using-rlm                 — emit enrichment plan(s) for an agent to dispatch
+ *   --filter <expr>             — restrict to artifacts matching expr
+ *   --force                     — re-enrich even when enriched_hash matches
+ *   --dry-run                   — count and estimate cost only
+ *   --reset                     — drop all enrichment data
+ *   --list                      — list current enrichment entries
+ *   --apply --id <id> --result <path>  — write a result back from agent dispatch
+ *
+ * Like `views build`, this CLI does NOT directly invoke RLM. It emits
+ * EnrichmentPlan records the agent acts on (dispatching /rlm-batch),
+ * then the agent writes results back via `--apply`.
+ *
+ * @implements #1204
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { computeHash } from '../../rlm/cache/hash.js';
+import { ENRICHMENT_PROMPT, validateEnrichmentOutput } from './prompt.js';
+import { computeContentHash, get as getEnrichment, has as hasEnrichment, list as listEnrichments, put as putEnrichment, reset as resetEnrichments, resolveSemanticRoot, } from './store.js';
+export async function main(args) {
+    if (args.includes('--reset')) {
+        handleReset();
+        return;
+    }
+    if (args.includes('--list')) {
+        handleList(args);
+        return;
+    }
+    if (args.includes('--apply')) {
+        handleApply(args);
+        return;
+    }
+    if (args.includes('--using-rlm')) {
+        handleUsingRlm(args);
+        return;
+    }
+    printUsage();
+    if (args.length > 0) {
+        process.exitCode = 1;
+    }
+}
+function asJson(args) {
+    return args.includes('--json');
+}
+function flagValue(args, flag) {
+    const i = args.indexOf(flag);
+    return i !== -1 && args[i + 1] ? args[i + 1] : undefined;
+}
+function handleReset() {
+    const root = resolveSemanticRoot();
+    const r = resetEnrichments(root);
+    console.log(`Reset enrichment: removed ${r.removed} sidecar entries from ${root}`);
+}
+function handleList(args) {
+    const root = resolveSemanticRoot();
+    const summaries = listEnrichments(root, /* currentHashes */ {});
+    if (asJson(args)) {
+        console.log(JSON.stringify(summaries, null, 2));
+        return;
+    }
+    if (summaries.length === 0) {
+        console.log('No enrichment entries.');
+        console.log(`Semantic root: ${root}`);
+        return;
+    }
+    console.log(`artifact                                       symbols  citations  age   stale`);
+    console.log(`─────────────────────────────────────────────  ───────  ─────────  ────  ─────`);
+    for (const s of summaries) {
+        const id = s.artifactId.length > 45 ? `…${s.artifactId.slice(-44)}` : s.artifactId.padEnd(45);
+        console.log(`${id}  ${String(s.symbolCount).padStart(7)}  ${String(s.citationCount).padStart(9)}  ${String(s.ageDays).padStart(3)}d  ${s.isStale ? 'YES' : ''}`);
+    }
+    console.log(`\n${summaries.length} entries at ${root}`);
+}
+function handleApply(args) {
+    const id = flagValue(args, '--id');
+    const result = flagValue(args, '--result');
+    if (!id || !result) {
+        console.error('Usage: aiwg index enrich --apply --id <id> --result <path-to-json>');
+        process.exitCode = 1;
+        return;
+    }
+    if (!existsSync(result)) {
+        console.error(`No file: ${result}`);
+        process.exitCode = 1;
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(result, 'utf-8'));
+    }
+    catch (err) {
+        console.error(`Failed to parse JSON: ${err.message}`);
+        process.exitCode = 1;
+        return;
+    }
+    const issues = validateEnrichmentOutput(parsed);
+    if (issues.length > 0) {
+        console.error('Enrichment result validation failed:');
+        for (const i of issues)
+            console.error(`  - ${i}`);
+        process.exitCode = 1;
+        return;
+    }
+    // Read the artifact to compute its current hash
+    const absId = resolve(id);
+    if (!existsSync(absId)) {
+        console.error(`Artifact not found at ${absId} — cannot compute content hash`);
+        process.exitCode = 1;
+        return;
+    }
+    const contentHash = computeContentHash(readFileSync(absId));
+    const r = parsed;
+    const fields = {
+        summary: r['summary'],
+        declaredSymbols: r['declared_symbols'],
+        citations: r['citations'],
+        inferredTags: r['inferred_tags'],
+        openQuestions: r['open_questions'],
+        enrichedAt: new Date().toISOString(),
+        enrichedBy: flagValue(args, '--by') ?? 'rlm-batch',
+        enrichedHash: contentHash,
+    };
+    const root = resolveSemanticRoot();
+    const file = putEnrichment(root, id, fields);
+    console.log(`Enrichment applied: ${id}`);
+    console.log(`  Written: ${file}`);
+}
+function handleUsingRlm(args) {
+    const filter = flagValue(args, '--filter');
+    const force = args.includes('--force');
+    const dryRun = args.includes('--dry-run');
+    const json = asJson(args);
+    const root = resolveSemanticRoot();
+    // Discover artifacts to enrich. We delegate target selection to the user
+    // via --files (one path per line, or comma-separated). This keeps the CLI
+    // free of an opinionated index walker; agents typically pass the file list
+    // they want enriched.
+    const filesArg = flagValue(args, '--files');
+    let files;
+    if (filesArg) {
+        if (existsSync(filesArg)) {
+            files = readFileSync(filesArg, 'utf-8')
+                .split(/\r?\n/)
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+        }
+        else {
+            files = filesArg.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+        }
+    }
+    else {
+        console.error('Usage: aiwg index enrich --using-rlm --files <path-to-list|csv> [--filter <expr>] [--force] [--dry-run]');
+        console.error('       aiwg index enrich --using-rlm --files src/foo.ts,src/bar.ts');
+        console.error('');
+        console.error('Tip: pipe `aiwg index query --json | jq -r .results[].path` into --files <path>.');
+        process.exitCode = 1;
+        return;
+    }
+    if (filter) {
+        const re = new RegExp(filter);
+        files = files.filter((f) => re.test(f));
+    }
+    // Filter by enrichment freshness unless --force
+    const plans = [];
+    let skipped = 0;
+    for (const f of files) {
+        if (!existsSync(f)) {
+            console.error(`[skip] missing: ${f}`);
+            continue;
+        }
+        const contentHash = computeContentHash(readFileSync(f));
+        if (!force && hasEnrichment(root, f)) {
+            try {
+                const existing = getEnrichment(root, f);
+                if (existing.enrichedHash === contentHash) {
+                    skipped++;
+                    continue;
+                }
+            }
+            catch { /* fall through to enrich */ }
+        }
+        const cacheKey = computeHash({
+            inputs: [{ artifactId: f, contentHash }],
+            query: ENRICHMENT_PROMPT,
+            subPrompt: ENRICHMENT_PROMPT,
+            model: 'claude-sonnet-4-6',
+            aggregateStrategy: 'json-merge',
+        });
+        plans.push({
+            artifactId: f,
+            contentHash,
+            prompt: ENRICHMENT_PROMPT,
+            outputPath: join(root, `${f.replace(/\//g, '__')}.json`),
+            cacheKey,
+        });
+    }
+    if (json) {
+        console.log(JSON.stringify({ plans, skipped, totalFiles: files.length }, null, 2));
+        return;
+    }
+    if (plans.length === 0) {
+        console.log(`No artifacts need enrichment (${skipped} already fresh, ${files.length} total).`);
+        if (!force)
+            console.log('Use --force to re-enrich regardless of hash.');
+        return;
+    }
+    console.log(`Enrichment plan: ${plans.length} artifact(s) to enrich, ${skipped} fresh, ${files.length} total.`);
+    if (dryRun) {
+        console.log('--dry-run: plan emitted, no dispatch.');
+        return;
+    }
+    console.log('');
+    console.log('NOTE: This command emits dispatch plans. The RLM agent (/rlm-batch) reads each plan,');
+    console.log('runs the canonical extraction prompt against the artifact, and applies the result via:');
+    console.log('  aiwg index enrich --apply --id <id> --result <path>');
+    console.log('');
+    for (const p of plans.slice(0, 10)) {
+        console.log(`  • ${p.artifactId}  (cache: ${p.cacheKey.slice(0, 12)}…)`);
+    }
+    if (plans.length > 10) {
+        console.log(`  … and ${plans.length - 10} more (use --json for full list)`);
+    }
+}
+function printUsage() {
+    console.log('aiwg index enrich [flags]');
+    console.log('');
+    console.log('Flags:');
+    console.log('  --using-rlm --files <path|csv>   Emit enrichment dispatch plans');
+    console.log('  --filter <regex>                 Restrict --using-rlm targets by regex');
+    console.log('  --force                          Re-enrich even when enriched_hash matches');
+    console.log('  --dry-run                        Plan without dispatch');
+    console.log('  --apply --id <id> --result <p>   Write back a single agent result');
+    console.log('  --list [--json]                  List current enrichment entries');
+    console.log('  --reset                          Drop all enrichment data (rollback)');
+}
+//# sourceMappingURL=cli.js.map

package/dist/src/artifacts/enrichment/prompt.js

@@ -0,0 +1,47 @@
+/**
+ * Canonical extraction prompt — single source of truth for semantic enrichment.
+ *
+ * The prompt instructs the dispatched RLM agent to read one artifact and
+ * return JSON matching the SemanticFields schema. Cache invalidation depends
+ * on this prompt being stable; changing it busts the cache for every
+ * previously-enriched artifact.
+ *
+ * @implements #1204
+ * @see .aiwg/architecture/adr-rlm-index-features-impl-plan.md
+ */
+export const ENRICHMENT_PROMPT = `Read the artifact below. Return JSON matching this schema exactly:
+
+{
+  "summary":          "<one paragraph, max 500 chars>",
+  "declared_symbols": ["<exported function / type / entity / class names>"],
+  "citations":        ["<REF-XXX | path/to/file.md | @-mention target>"],
+  "inferred_tags":    ["<topic keywords from the content>"],
+  "open_questions":   ["<contradictions or open questions stated in the artifact>"]
+}
+
+Be conservative: empty arrays are fine when nothing applies. Do not fabricate citations or symbols not present in the source. Do not include the artifact's title or path in the summary — write the summary as if the reader already knows what file they are reading.
+
+Output ONLY the JSON object, no surrounding prose.`;
+/** Validate raw RLM output against the SemanticFields shape. Returns issues, empty if valid. */
+export function validateEnrichmentOutput(raw) {
+    const issues = [];
+    if (!raw || typeof raw !== 'object') {
+        return ['enrichment output must be a JSON object'];
+    }
+    const r = raw;
+    if (typeof r['summary'] !== 'string')
+        issues.push('summary must be a string');
+    else if (r['summary'].length > 1000)
+        issues.push('summary exceeds 1000 chars');
+    for (const arrField of ['declared_symbols', 'citations', 'inferred_tags', 'open_questions']) {
+        const v = r[arrField];
+        if (!Array.isArray(v)) {
+            issues.push(`${arrField} must be a string array`);
+        }
+        else if (v.some((item) => typeof item !== 'string')) {
+            issues.push(`${arrField} must contain only strings`);
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=prompt.js.map