@karmaniverous/jeeves-meta 0.8.0 → 0.10.0

package/dist/cli/jeeves-meta/index.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
-import fs, { readFileSync, readdirSync, unlinkSync, mkdirSync, writeFileSync, existsSync, statSync, copyFileSync, watchFile } from 'node:fs';
-import path, { dirname, join, resolve, relative } from 'node:path';
+import fs, { readFileSync, readdirSync, unlinkSync, existsSync, writeFileSync, statSync, mkdirSync, watchFile } from 'node:fs';
+import path, { dirname, join, resolve, relative, posix } from 'node:path';
 import { z } from 'zod';
 import { fileURLToPath } from 'node:url';
-import 'node:fs/promises';
+import { unlink, readFile, mkdir, writeFile, copyFile } from 'node:fs/promises';
 import process$1 from 'node:process';
 import { createHash, randomUUID } from 'node:crypto';
 import { tmpdir } from 'node:os';
@@ -72,6 +72,15 @@ const loggingSchema = z.object({
     /** Optional file path for log output. */
     file: z.string().optional(),
 });
+/** Zod schema for a single auto-seed policy rule. */
+const autoSeedRuleSchema = z.object({
+    /** Glob pattern matched against watcher walk results. */
+    match: z.string(),
+    /** Optional steering prompt for seeded metas. */
+    steer: z.string().optional(),
+    /** Optional cross-references for seeded metas. */
+    crossRefs: z.array(z.string()).optional(),
+});
 /** Zod schema for jeeves-meta service configuration (superset of MetaConfig). */
 const serviceConfigSchema = metaConfigSchema.extend({
     /** HTTP port for the service (default: 1938). */
@@ -88,6 +97,11 @@ const serviceConfigSchema = metaConfigSchema.extend({
     watcherHealthIntervalMs: z.number().int().min(0).default(60_000),
     /** Logging configuration. */
     logging: loggingSchema.default(() => loggingSchema.parse({})),
+    /**
+     * Auto-seed policy: declarative rules for auto-creating .meta/ directories.
+     * Rules are evaluated in order; last match wins for steer/crossRefs.
+     */
+    autoSeed: z.array(autoSeedRuleSchema).optional().default([]),
 });
 
 /**
@@ -338,14 +352,12 @@ function listArchiveFiles(metaPath) {
  * @param maxArchive - Maximum snapshots to retain.
  * @returns Number of files pruned.
  */
-function pruneArchive(metaPath, maxArchive) {
+async function pruneArchive(metaPath, maxArchive) {
     const files = listArchiveFiles(metaPath);
     const toRemove = files.length - maxArchive;
     if (toRemove <= 0)
         return 0;
-    for (let i = 0; i < toRemove; i++) {
-        unlinkSync(files[i]);
-    }
+    await Promise.all(files.slice(0, toRemove).map(unlink));
     return toRemove;
 }
 
@@ -360,11 +372,11 @@ function pruneArchive(metaPath, maxArchive) {
  * @param metaPath - Absolute path to the .meta directory.
  * @returns The latest archived meta, or null if no archives exist.
  */
-function readLatestArchive(metaPath) {
+async function readLatestArchive(metaPath) {
     const files = listArchiveFiles(metaPath);
     if (files.length === 0)
         return null;
-    const raw = readFileSync(files[files.length - 1], 'utf8');
+    const raw = await readFile(files[files.length - 1], 'utf8');
     return JSON.parse(raw);
 }
 
@@ -383,9 +395,9 @@ function readLatestArchive(metaPath) {
  * @param meta - Current meta.json content.
  * @returns The archive file path.
  */
-function createSnapshot(metaPath, meta) {
+async function createSnapshot(metaPath, meta) {
     const archiveDir = join(metaPath, 'archive');
-    mkdirSync(archiveDir, { recursive: true });
+    await mkdir(archiveDir, { recursive: true });
     const now = new Date().toISOString().replace(/[:.]/g, '-');
     const archiveFile = join(archiveDir, now + '.json');
     const archived = {
@@ -393,10 +405,79 @@ function createSnapshot(metaPath, meta) {
         _archived: true,
         _archivedAt: new Date().toISOString(),
     };
-    writeFileSync(archiveFile, JSON.stringify(archived, null, 2) + '\n');
+    await writeFile(archiveFile, JSON.stringify(archived, null, 2) + '\n');
     return archiveFile;
 }
 
+/**
+ * Compute summary statistics from an array of MetaEntry objects.
+ *
+ * Shared between listMetas() (full list) and route handlers (filtered lists).
+ *
+ * @module discovery/computeSummary
+ */
+/**
+ * Compute summary statistics from a list of meta entries.
+ *
+ * @param entries - Enriched meta entries (full or filtered).
+ * @param depthWeight - Config depth weight for effective staleness calculation.
+ * @returns Aggregated summary statistics.
+ */
+function computeSummary(entries, depthWeight) {
+    let staleCount = 0;
+    let errorCount = 0;
+    let lockedCount = 0;
+    let neverSynthesizedCount = 0;
+    let totalArchitectTokens = 0;
+    let totalBuilderTokens = 0;
+    let totalCriticTokens = 0;
+    let stalestPath = null;
+    let stalestEffective = -1;
+    let lastSynthesizedPath = null;
+    let lastSynthesizedAt = null;
+    for (const e of entries) {
+        if (e.stalenessSeconds > 0)
+            staleCount++;
+        if (e.hasError)
+            errorCount++;
+        if (e.locked)
+            lockedCount++;
+        if (e.lastSynthesized === null)
+            neverSynthesizedCount++;
+        totalArchitectTokens += e.architectTokens ?? 0;
+        totalBuilderTokens += e.builderTokens ?? 0;
+        totalCriticTokens += e.criticTokens ?? 0;
+        // Track last synthesized
+        if (e.lastSynthesized &&
+            (!lastSynthesizedAt || e.lastSynthesized > lastSynthesizedAt)) {
+            lastSynthesizedAt = e.lastSynthesized;
+            lastSynthesizedPath = e.path;
+        }
+        // Track stalest (effective staleness for scheduling)
+        const depthFactor = Math.pow(1 + depthWeight, e.depth);
+        const effectiveStaleness = e.stalenessSeconds * depthFactor * e.emphasis;
+        if (effectiveStaleness > stalestEffective) {
+            stalestEffective = effectiveStaleness;
+            stalestPath = e.path;
+        }
+    }
+    return {
+        total: entries.length,
+        stale: staleCount,
+        errors: errorCount,
+        locked: lockedCount,
+        neverSynthesized: neverSynthesizedCount,
+        tokens: {
+            architect: totalArchitectTokens,
+            builder: totalBuilderTokens,
+            critic: totalCriticTokens,
+        },
+        stalestPath,
+        lastSynthesizedPath,
+        lastSynthesizedAt,
+    };
+}
+
 /**
  * Normalize file paths to forward slashes for consistency with watcher-indexed paths.
  *
@@ -589,14 +670,15 @@ function cleanupStaleLocks(metaPaths, logger) {
  * @module readMetaJson
  */
 /**
- * Read and parse a meta.json file from a `.meta/` directory path.
+ * Read and parse a meta.json file from a `.meta/` directory path (async).
  *
  * @param metaPath - Path to the `.meta/` directory.
  * @returns Parsed meta.json content.
  * @throws If the file doesn't exist or contains invalid JSON.
  */
-function readMetaJson(metaPath) {
-    return JSON.parse(readFileSync(join(metaPath, 'meta.json'), 'utf8'));
+async function readMetaJson(metaPath) {
+    const raw = await readFile(join(metaPath, 'meta.json'), 'utf8');
+    return JSON.parse(raw);
 }
 
 /**
@@ -701,21 +783,10 @@ async function listMetas(config, watcher) {
     const tree = buildOwnershipTree(metaPaths);
     // Step 3: Read and enrich each meta from disk
     const entries = [];
-    let staleCount = 0;
-    let errorCount = 0;
-    let lockedCount = 0;
-    let neverSynthesizedCount = 0;
-    let totalArchTokens = 0;
-    let totalBuilderTokens = 0;
-    let totalCriticTokens = 0;
-    let lastSynthPath = null;
-    let lastSynthAt = null;
-    let stalestPath = null;
-    let stalestEffective = -1;
     for (const node of tree.nodes.values()) {
         let meta;
         try {
-            meta = readMetaJson(node.metaPath);
+            meta = await readMetaJson(node.metaPath);
         }
         catch {
             // Skip unreadable metas
@@ -739,32 +810,6 @@ async function listMetas(config, watcher) {
         const archTokens = meta._architectTokens ?? 0;
         const buildTokens = meta._builderTokens ?? 0;
         const critTokens = meta._criticTokens ?? 0;
-        // Accumulate summary stats
-        if (stalenessSeconds > 0)
-            staleCount++;
-        if (hasError)
-            errorCount++;
-        if (locked)
-            lockedCount++;
-        if (neverSynth)
-            neverSynthesizedCount++;
-        totalArchTokens += archTokens;
-        totalBuilderTokens += buildTokens;
-        totalCriticTokens += critTokens;
-        // Track last synthesized
-        if (meta._generatedAt) {
-            if (!lastSynthAt || meta._generatedAt > lastSynthAt) {
-                lastSynthAt = meta._generatedAt;
-                lastSynthPath = node.metaPath;
-            }
-        }
-        // Track stalest (effective staleness for scheduling)
-        const depthFactor = Math.pow(1 + config.depthWeight, depth);
-        const effectiveStaleness = stalenessSeconds * depthFactor * emphasis;
-        if (effectiveStaleness > stalestEffective) {
-            stalestEffective = effectiveStaleness;
-            stalestPath = node.metaPath;
-        }
         entries.push({
             path: node.metaPath,
             depth,
@@ -782,21 +827,7 @@ async function listMetas(config, watcher) {
         });
     }
     return {
-        summary: {
-            total: entries.length,
-            stale: staleCount,
-            errors: errorCount,
-            locked: lockedCount,
-            neverSynthesized: neverSynthesizedCount,
-            tokens: {
-                architect: totalArchTokens,
-                builder: totalBuilderTokens,
-                critic: totalCriticTokens,
-            },
-            stalestPath,
-            lastSynthesizedPath: lastSynthPath,
-            lastSynthesizedAt: lastSynthAt,
-        },
+        summary: computeSummary(entries, config.depthWeight),
         entries,
         tree,
     };
@@ -900,12 +931,17 @@ function filterInScope(node, files) {
 /**
  * Get all files in scope for a meta node via watcher walk.
  */
-async function getScopeFiles(node, watcher) {
+async function getScopeFiles(node, watcher, logger) {
+    const walkStart = Date.now();
     const allFiles = await watcher.walk([`${node.ownerPath}/**`]);
-    return {
-        scopeFiles: filterInScope(node, allFiles),
-        allFiles,
-    };
+    const scopeFiles = filterInScope(node, allFiles);
+    logger?.debug({
+        ownerPath: node.ownerPath,
+        allFiles: allFiles.length,
+        scopeFiles: scopeFiles.length,
+        durationMs: Date.now() - walkStart,
+    }, 'scope files enumerated');
+    return { scopeFiles, allFiles };
 }
 /**
  * Get files modified since a given timestamp within a meta node's scope.
@@ -1230,6 +1266,22 @@ function condenseScopeFiles(files, maxIndividual = 30) {
         .map(([pattern, count]) => pattern + ' (' + count.toString() + ' files)')
         .join('\n');
 }
+/**
+ * Read a meta.json file and extract its `_content` field.
+ *
+ * @param metaJsonPath - Absolute path to a meta.json file.
+ * @returns The `_content` string, or null if missing/unreadable.
+ */
+async function readMetaContent(metaJsonPath) {
+    try {
+        const raw = await readFile(metaJsonPath, 'utf8');
+        const meta = JSON.parse(raw);
+        return meta._content ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Build the context package for a synthesis cycle.
  *
@@ -1238,22 +1290,43 @@ function condenseScopeFiles(files, maxIndividual = 30) {
  * @param watcher - WatcherClient for scope enumeration.
  * @returns The computed context package.
  */
-async function buildContextPackage(node, meta, watcher) {
+async function buildContextPackage(node, meta, watcher, logger) {
     // Scope and delta files via watcher walk
-    const { scopeFiles } = await getScopeFiles(node, watcher);
+    const scopeStart = Date.now();
+    const { scopeFiles } = await getScopeFiles(node, watcher, logger);
     const deltaFiles = getDeltaFiles(meta._generatedAt, scopeFiles);
-    // Child meta outputs
+    logger?.debug({
+        scopeFiles: scopeFiles.length,
+        deltaFiles: deltaFiles.length,
+        durationMs: Date.now() - scopeStart,
+    }, 'scope and delta files computed');
+    // Child meta outputs (parallel reads)
     const childMetas = {};
-    for (const child of node.children) {
-        const childMetaFile = join(child.metaPath, 'meta.json');
-        try {
-            const raw = readFileSync(childMetaFile, 'utf8');
-            const childMeta = JSON.parse(raw);
-            childMetas[child.ownerPath] = childMeta._content ?? null;
-        }
-        catch {
-            childMetas[child.ownerPath] = null;
-        }
+    const childEntries = await Promise.all(node.children.map(async (child) => {
+        const content = await readMetaContent(join(child.metaPath, 'meta.json'));
+        return [child.ownerPath, content];
+    }));
+    for (const [path, content] of childEntries) {
+        childMetas[path] = content;
+    }
+    // Cross-referenced meta outputs (parallel reads)
+    const crossRefMetas = {};
+    const seen = new Set();
+    const crossRefPaths = [];
+    for (const refPath of meta._crossRefs ?? []) {
+        if (refPath === node.ownerPath || refPath === node.metaPath)
+            continue;
+        if (seen.has(refPath))
+            continue;
+        seen.add(refPath);
+        crossRefPaths.push(refPath);
+    }
+    const crossRefEntries = await Promise.all(crossRefPaths.map(async (refPath) => {
+        const content = await readMetaContent(join(refPath, '.meta', 'meta.json'));
+        return [refPath, content];
+    }));
+    for (const [path, content] of crossRefEntries) {
+        crossRefMetas[path] = content;
     }
     // Archive paths
     const archives = listArchiveFiles(node.metaPath);
@@ -1262,6 +1335,7 @@ async function buildContextPackage(node, meta, watcher) {
         scopeFiles,
         deltaFiles,
         childMetas,
+        crossRefMetas,
         previousContent: meta._content ?? null,
         previousFeedback: meta._feedback ?? null,
         steer: meta._steer ?? null,
@@ -1275,6 +1349,15 @@ async function buildContextPackage(node, meta, watcher) {
  *
  * @module orchestrator/buildTask
  */
+/** Append a keyed record of meta outputs as subsections, if non-empty. */
+function appendMetaSections(sections, heading, metas) {
+    if (Object.keys(metas).length === 0)
+        return;
+    sections.push('', heading);
+    for (const [path, content] of Object.entries(metas)) {
+        sections.push(`### ${path}`, typeof content === 'string' ? content : '(not yet synthesized)');
+    }
+}
 /** Append optional context sections shared across all step prompts. */
 function appendSharedSections(sections, ctx, options) {
     const opts = {
@@ -1283,6 +1366,7 @@ function appendSharedSections(sections, ctx, options) {
         includePreviousFeedback: true,
         feedbackHeading: '## PREVIOUS FEEDBACK',
         includeChildMetas: true,
+        includeCrossRefs: true,
         ...options,
     };
     if (opts.includeSteer && ctx.steer) {
@@ -1294,11 +1378,11 @@ function appendSharedSections(sections, ctx, options) {
     if (opts.includePreviousFeedback && ctx.previousFeedback) {
         sections.push('', opts.feedbackHeading, ctx.previousFeedback);
     }
-    if (opts.includeChildMetas && Object.keys(ctx.childMetas).length > 0) {
-        sections.push('', '## CHILD META OUTPUTS');
-        for (const [childPath, content] of Object.entries(ctx.childMetas)) {
-            sections.push(`### ${childPath}`, typeof content === 'string' ? content : '(not yet synthesized)');
-        }
+    if (opts.includeChildMetas) {
+        appendMetaSections(sections, '## CHILD META OUTPUTS', ctx.childMetas);
+    }
+    if (opts.includeCrossRefs) {
+        appendMetaSections(sections, '## CROSS-REFERENCED METAS', ctx.crossRefMetas);
     }
 }
 /**
@@ -1382,6 +1466,7 @@ function buildCriticTask(ctx, meta, config) {
         includePreviousContent: false,
         feedbackHeading: '## YOUR PREVIOUS FEEDBACK',
         includeChildMetas: false,
+        includeCrossRefs: false,
     });
     sections.push('', '## OUTPUT FORMAT', 'Return your evaluation as Markdown text. Be specific and actionable.');
     return sections.join('\n');
@@ -1413,10 +1498,15 @@ const metaErrorSchema = z.object({
 /** Zod schema for the reserved (underscore-prefixed) meta.json properties. */
 const metaJsonSchema = z
     .object({
-    /** Stable identity. Generated on first synthesis, never changes. */
-    _id: z.uuid(),
+    /** Stable identity. Auto-generated on first synthesis if not provided. */
+    _id: z.uuid().optional(),
     /** Human-provided steering prompt. Optional. */
     _steer: z.string().optional(),
+    /**
+     * Explicit cross-references to other meta owner paths.
+     * Referenced metas' _content is included as architect/builder context.
+     */
+    _crossRefs: z.array(z.string()).optional(),
     /** Architect system prompt used this turn. Defaults from config. */
     _architect: z.string().optional(),
     /**
@@ -1502,10 +1592,10 @@ const metaJsonSchema = z
  * @returns The updated MetaJson.
  * @throws If validation fails (malformed output).
  */
-function mergeAndWrite(options) {
+async function mergeAndWrite(options) {
     const merged = {
-        // Preserve human-set fields
-        _id: options.current._id,
+        // Preserve human-set fields (auto-generate _id on first synthesis)
+        _id: options.current._id ?? randomUUID(),
         _steer: options.current._steer,
         _depth: options.current._depth,
         _emphasis: options.current._emphasis,
@@ -1578,7 +1668,7 @@ function mergeAndWrite(options) {
     }
     // Write to specified path (lock staging) or default meta.json
     const filePath = options.outputPath ?? join(options.metaPath, 'meta.json');
-    writeFileSync(filePath, JSON.stringify(result.data, null, 2) + '\n');
+    await writeFile(filePath, JSON.stringify(result.data, null, 2) + '\n');
     return result.data;
 }
 
@@ -1818,11 +1908,11 @@ function computeStalenessScore(stalenessSeconds, depth, emphasis, depthWeight) {
  * @module orchestrator/finalizeCycle
  */
 /** Finalize a cycle using lock staging: write to .lock → copy to meta.json + archive → delete .lock. */
-function finalizeCycle(opts) {
+async function finalizeCycle(opts) {
     const lockPath = join(opts.metaPath, '.lock');
     const metaJsonPath = join(opts.metaPath, 'meta.json');
-    // Stage: write merged result to .lock
-    const updated = mergeAndWrite({
+    // Stage: write merged result to .lock (sequential — ordering matters)
+    const updated = await mergeAndWrite({
         metaPath: opts.metaPath,
         current: opts.current,
         architect: opts.architect,
@@ -1841,10 +1931,10 @@ function finalizeCycle(opts) {
         stateOnly: opts.stateOnly,
     });
     // Commit: copy .lock → meta.json
-    copyFileSync(lockPath, metaJsonPath);
-    // Archive + prune from the committed meta.json
-    createSnapshot(opts.metaPath, updated);
-    pruneArchive(opts.metaPath, opts.config.maxArchive);
+    await copyFile(lockPath, metaJsonPath);
+    // Archive + prune from the committed meta.json (sequential)
+    await createSnapshot(opts.metaPath, updated);
+    await pruneArchive(opts.metaPath, opts.config.maxArchive);
     // .lock is cleaned up by the finally block (releaseLock)
     return updated;
 }
@@ -1957,14 +2047,12 @@ function parseCriticOutput(output) {
  * Returns an {@link OrchestrateResult} if state was salvaged, or `null`
  * if the caller should fall through to a hard failure.
  */
-function attemptTimeoutRecovery(opts) {
+async function attemptTimeoutRecovery(opts) {
     const { err, currentMeta, metaPath, config, builderBrief, structureHash, synthesisCount, } = opts;
     let partialOutput = null;
     try {
-        if (existsSync(err.outputPath)) {
-            const raw = readFileSync(err.outputPath, 'utf8');
-            partialOutput = parseBuilderOutput(raw);
-        }
+        const raw = await readFile(err.outputPath, 'utf8');
+        partialOutput = parseBuilderOutput(raw);
     }
     catch {
         // Could not read partial output — fall through to hard failure
@@ -1978,7 +2066,7 @@ function attemptTimeoutRecovery(opts) {
                 code: 'TIMEOUT',
                 message: err.message,
             };
-            finalizeCycle({
+            await finalizeCycle({
                 metaPath,
                 current: currentMeta,
                 config,
@@ -2009,12 +2097,12 @@ function attemptTimeoutRecovery(opts) {
  * @module orchestrator/synthesizeNode
  */
 /** Run the architect/builder/critic pipeline on a single node. */
-async function synthesizeNode(node, currentMeta, config, executor, watcher, onProgress) {
+async function synthesizeNode(node, currentMeta, config, executor, watcher, onProgress, logger) {
     // Step 5-6: Steer change detection
-    const latestArchive = readLatestArchive(node.metaPath);
+    const latestArchive = await readLatestArchive(node.metaPath);
     const steerChanged = hasSteerChanged(currentMeta._steer, latestArchive?._steer, Boolean(latestArchive));
     // Step 7: Compute context (includes scope files and delta files)
-    const ctx = await buildContextPackage(node, currentMeta, watcher);
+    const ctx = await buildContextPackage(node, currentMeta, watcher, logger);
     // Step 5 (deferred): Structure hash from context scope files
     const newStructureHash = computeStructureHash(ctx.scopeFiles);
     const structureChanged = newStructureHash !== currentMeta._structureHash;
@@ -2026,6 +2114,16 @@ async function synthesizeNode(node, currentMeta, config, executor, watcher, onPr
     let architectTokens;
     let builderTokens;
     let criticTokens;
+    // Shared base options for all finalizeCycle calls.
+    // Note: synthesisCount is excluded because it mutates during the pipeline.
+    const baseFinalizeOptions = {
+        metaPath: node.metaPath,
+        current: currentMeta,
+        config,
+        architect: currentMeta._architect ?? '',
+        critic: currentMeta._critic ?? '',
+        structureHash: newStructureHash,
+    };
     if (architectTriggered) {
         try {
             await onProgress?.({
@@ -2054,16 +2152,11 @@ async function synthesizeNode(node, currentMeta, config, executor, watcher, onPr
             stepError = toMetaError('architect', err);
             if (!currentMeta._builder) {
                 // No cached builder — cycle fails
-                finalizeCycle({
-                    metaPath: node.metaPath,
-                    current: currentMeta,
-                    config,
-                    architect: currentMeta._architect ?? '',
+                await finalizeCycle({
+                    ...baseFinalizeOptions,
                     builder: '',
-                    critic: currentMeta._critic ?? '',
                     builderOutput: null,
                     feedback: null,
-                    structureHash: newStructureHash,
                     synthesisCount,
                     error: stepError,
                     architectTokens,
@@ -2105,7 +2198,7 @@ async function synthesizeNode(node, currentMeta, config, executor, watcher, onPr
     }
     catch (err) {
         if (err instanceof SpawnTimeoutError) {
-            const recovered = attemptTimeoutRecovery({
+            const recovered = await attemptTimeoutRecovery({
                 err,
                 currentMeta,
                 metaPath: node.metaPath,
@@ -2118,16 +2211,11 @@ async function synthesizeNode(node, currentMeta, config, executor, watcher, onPr
                 return recovered;
         }
         stepError = toMetaError('builder', err);
-        finalizeCycle({
-            metaPath: node.metaPath,
-            current: currentMeta,
-            config,
-            architect: currentMeta._architect ?? '',
+        await finalizeCycle({
+            ...baseFinalizeOptions,
             builder: builderBrief,
-            critic: currentMeta._critic ?? '',
             builderOutput: null,
             feedback: null,
-            structureHash: newStructureHash,
             synthesisCount,
             error: stepError,
         });
@@ -2166,16 +2254,11 @@ async function synthesizeNode(node, currentMeta, config, executor, watcher, onPr
         stepError = stepError ?? toMetaError('critic', err);
     }
     // Steps 11-12: Merge, archive, prune
-    finalizeCycle({
-        metaPath: node.metaPath,
-        current: currentMeta,
-        config,
-        architect: currentMeta._architect ?? '',
+    await finalizeCycle({
+        ...baseFinalizeOptions,
         builder: builderBrief,
-        critic: currentMeta._critic ?? '',
         builderOutput,
         feedback,
-        structureHash: newStructureHash,
         synthesisCount,
         error: stepError,
         architectTokens,
@@ -2207,21 +2290,25 @@ async function orchestrateOnce(config, executor, watcher, targetPath, onProgress
         if (!acquireLock(node.metaPath))
             return { synthesized: false };
         try {
-            const currentMeta = readMetaJson(normalizedTarget);
-            return await synthesizeNode(node, currentMeta, config, executor, watcher, onProgress);
+            const currentMeta = await readMetaJson(normalizedTarget);
+            return await synthesizeNode(node, currentMeta, config, executor, watcher, onProgress, logger);
         }
         finally {
             releaseLock(node.metaPath);
         }
     }
+    // Full discovery path (scheduler-driven, no specific target)
+    // Step 1: Discover via watcher walk
+    const discoveryStart = Date.now();
     const metaPaths = await discoverMetas(watcher);
+    logger?.debug({ paths: metaPaths.length, durationMs: Date.now() - discoveryStart }, 'discovery complete');
     if (metaPaths.length === 0)
         return { synthesized: false };
     // Read meta.json for each discovered meta
     const metas = new Map();
     for (const mp of metaPaths) {
         try {
-            metas.set(normalizePath(mp), readMetaJson(mp));
+            metas.set(normalizePath(mp), await readMetaJson(mp));
         }
         catch {
             // Skip metas with unreadable meta.json
@@ -2257,9 +2344,9 @@ async function orchestrateOnce(config, executor, watcher, targetPath, onProgress
         const verifiedStale = await isStale(getScopePrefix(candidate.node), candidate.meta, watcher);
         if (!verifiedStale && candidate.meta._generatedAt) {
             // Bump _generatedAt so it doesn't win next cycle
-            const freshMeta = readMetaJson(candidate.node.metaPath);
+            const freshMeta = await readMetaJson(candidate.node.metaPath);
             freshMeta._generatedAt = new Date().toISOString();
-            writeFileSync(join(candidate.node.metaPath, 'meta.json'), JSON.stringify(freshMeta, null, 2));
+            await writeFile(join(candidate.node.metaPath, 'meta.json'), JSON.stringify(freshMeta, null, 2));
             releaseLock(candidate.node.metaPath);
             if (config.skipUnchanged)
                 continue;
@@ -2272,8 +2359,8 @@ async function orchestrateOnce(config, executor, watcher, targetPath, onProgress
         return { synthesized: false };
     const node = winner.node;
     try {
-        const currentMeta = readMetaJson(node.metaPath);
-        return await synthesizeNode(node, currentMeta, config, executor, watcher, onProgress);
+        const currentMeta = await readMetaJson(node.metaPath);
+        return await synthesizeNode(node, currentMeta, config, executor, watcher, onProgress, logger);
     }
     finally {
         // Step 13: Release lock
@@ -2293,7 +2380,7 @@ async function orchestrateOnce(config, executor, watcher, targetPath, onProgress
  * @returns Array with a single result.
  */
 async function orchestrate(config, executor, watcher, targetPath, onProgress, logger) {
-    const result = await orchestrateOnce(config, executor, watcher, targetPath, onProgress);
+    const result = await orchestrateOnce(config, executor, watcher, targetPath, onProgress, logger);
     return [result];
 }
 
@@ -2312,14 +2399,15 @@ function formatSeconds(durationMs) {
 function titleCasePhase(phase) {
     return phase.charAt(0).toUpperCase() + phase.slice(1);
 }
-/** Build a link for the entity path, if serverBaseUrl is available. */
+/** Build a link to the entity's meta.json output file. */
 function buildEntityLink(path, serverBaseUrl) {
+    // Normalize backslashes, then convert drive letter to URL path segment
+    const normalized = normalizePath(path).replace(/^([A-Za-z]):/, '/$1');
+    const metaJsonPath = `${normalized}/.meta/meta.json`;
     if (!serverBaseUrl)
-        return path;
+        return metaJsonPath;
     const base = serverBaseUrl.replace(/\/+$/, '');
-    // Convert Windows-style path to /drive/rest format: D:\foo → /D/foo
-    const normalized = path.replace(/^([A-Za-z]):/, '/$1').replace(/\\/g, '/');
-    return `${base}/path${normalized}`;
+    return `${base}/path${metaJsonPath}`;
 }
 function formatProgressEvent(event, serverBaseUrl) {
     const pathDisplay = buildEntityLink(event.path, serverBaseUrl);
@@ -2398,6 +2486,123 @@ class ProgressReporter {
     }
 }
 
+/**
+ * Core seed logic — create a .meta/ directory with initial meta.json.
+ *
+ * Shared between the POST /seed route handler and the auto-seed pass.
+ *
+ * @module seed/createMeta
+ */
+/**
+ * Create a .meta/ directory with an initial meta.json.
+ *
+ * Does NOT check for existing .meta/ — caller is responsible for that guard.
+ *
+ * @param ownerPath - The owner directory path.
+ * @param options - Optional cross-refs and steering prompt.
+ * @returns The meta directory path and generated ID.
+ */
+async function createMeta(ownerPath, options) {
+    const metaDir = resolveMetaDir(ownerPath);
+    await mkdir(metaDir, { recursive: true });
+    const _id = randomUUID();
+    const metaJson = { _id };
+    if (options?.crossRefs !== undefined)
+        metaJson._crossRefs = options.crossRefs;
+    if (options?.steer !== undefined)
+        metaJson._steer = options.steer;
+    const metaJsonPath = join(metaDir, 'meta.json');
+    await writeFile(metaJsonPath, JSON.stringify(metaJson, null, 2) + '\n');
+    return { metaDir, _id };
+}
+/**
+ * Check if a .meta/ directory already exists for an owner path.
+ *
+ * @param ownerPath - The owner directory path.
+ * @returns True if .meta/ already exists.
+ */
+function metaExists(ownerPath) {
+    return existsSync(resolveMetaDir(ownerPath));
+}
+
+/**
+ * Auto-seed pass — scan for directories matching policy rules and seed them.
+ *
+ * Runs before discovery in each scheduler tick. For each auto-seed rule,
+ * walks matching directories via the watcher and creates .meta/ directories
+ * for those that don't already have one.
+ *
+ * Rules are processed in array order; last match wins for steer/crossRefs.
+ *
+ * @module seed/autoSeed
+ */
+/**
+ * Extract parent directory paths from watcher walk results.
+ *
+ * Walk returns file paths; we need the unique set of immediate parent
+ * directories that could be owners.
+ */
+function extractDirectories(filePaths) {
+    const dirs = new Set();
+    for (const fp of filePaths) {
+        const dir = posix.dirname(fp);
+        if (dir !== '.' && dir !== '/') {
+            dirs.add(dir);
+        }
+    }
+    return [...dirs];
+}
+/**
+ * Run the auto-seed pass: apply policy rules and create missing metas.
+ *
+ * @param rules - Auto-seed policy rules from config.
+ * @param watcher - Watcher client for filesystem enumeration.
+ * @param logger - Logger for reporting seed actions.
+ * @returns Summary of what was seeded.
+ */
+async function autoSeedPass(rules, watcher, logger) {
+    if (rules.length === 0)
+        return { seeded: 0, paths: [] };
+    // Build a map of ownerPath → effective options (last match wins)
+    const candidates = new Map();
+    for (const rule of rules) {
+        const files = await watcher.walk([rule.match]);
+        const dirs = extractDirectories(files);
+        for (const dir of dirs) {
+            candidates.set(dir, {
+                steer: rule.steer,
+                crossRefs: rule.crossRefs,
+            });
+        }
+    }
+    // Filter out paths that already have .meta/meta.json
+    const toSeed = [];
+    for (const [path, opts] of candidates) {
+        if (!metaExists(path)) {
+            toSeed.push({ path, ...opts });
+        }
+    }
+    // Seed remaining
+    const seededPaths = [];
+    for (const candidate of toSeed) {
+        try {
+            await createMeta(candidate.path, {
+                steer: candidate.steer,
+                crossRefs: candidate.crossRefs,
+            });
+            seededPaths.push(candidate.path);
+            logger?.info({ path: candidate.path }, 'auto-seeded meta');
+        }
+        catch (err) {
+            logger?.warn({
+                path: candidate.path,
+                err: err instanceof Error ? err.message : String(err),
+            }, 'auto-seed failed for path');
+        }
+    }
+    return { seeded: seededPaths.length, paths: seededPaths };
+}
+
 /**
  * Croner-based scheduler that discovers the stalest meta candidate each tick
  * and enqueues it for synthesis.
@@ -2495,6 +2700,18 @@ class Scheduler {
             }, 'Skipping tick (backoff)');
             return;
         }
+        // Auto-seed pass: create .meta/ for matching directories
+        if (this.config.autoSeed.length > 0) {
+            try {
+                const result = await autoSeedPass(this.config.autoSeed, this.watcher, this.logger);
+                if (result.seeded > 0) {
+                    this.logger.info({ seeded: result.seeded }, 'Auto-seed pass completed');
+                }
+            }
+            catch (err) {
+                this.logger.warn({ err }, 'Auto-seed pass failed');
+            }
+        }
         const candidate = await this.discoverStalest();
         if (!candidate) {
             this.backoffMultiplier = Math.min(this.backoffMultiplier * 2, MAX_BACKOFF_MULTIPLIER);
@@ -9750,53 +9967,6 @@ const metaDetailQuerySchema = z.object({
     ])
         .optional(),
 });
-/** Compute summary stats from a filtered set of MetaEntries. */
-function computeFilteredSummary(entries) {
-    let staleCount = 0;
-    let errorCount = 0;
-    let neverSynthCount = 0;
-    let stalestPath = null;
-    let stalestSeconds = -1;
-    let lastSynthesizedPath = null;
-    let lastSynthesizedAt = null;
-    let totalArchitectTokens = 0;
-    let totalBuilderTokens = 0;
-    let totalCriticTokens = 0;
-    for (const e of entries) {
-        if (e.stalenessSeconds > 0)
-            staleCount++;
-        if (e.hasError)
-            errorCount++;
-        if (e.stalenessSeconds === Infinity)
-            neverSynthCount++;
-        if (e.stalenessSeconds > stalestSeconds) {
-            stalestSeconds = e.stalenessSeconds;
-            stalestPath = e.path;
-        }
-        if (e.lastSynthesized &&
-            (!lastSynthesizedAt || e.lastSynthesized > lastSynthesizedAt)) {
-            lastSynthesizedAt = e.lastSynthesized;
-            lastSynthesizedPath = e.path;
-        }
-        totalArchitectTokens += e.architectTokens ?? 0;
-        totalBuilderTokens += e.builderTokens ?? 0;
-        totalCriticTokens += e.criticTokens ?? 0;
-    }
-    return {
-        total: entries.length,
-        stale: staleCount,
-        errors: errorCount,
-        neverSynthesized: neverSynthCount,
-        stalestPath,
-        lastSynthesizedPath,
-        lastSynthesizedAt,
-        tokens: {
-            architect: totalArchitectTokens,
-            builder: totalBuilderTokens,
-            critic: totalCriticTokens,
-        },
-    };
-}
 function registerMetasRoutes(app, deps) {
     app.get('/metas', async (request) => {
         const query = metasQuerySchema.parse(request.query);
@@ -9811,7 +9981,7 @@ function registerMetasRoutes(app, deps) {
             entries = entries.filter((e) => e.hasError === query.hasError);
         }
         if (query.neverSynthesized !== undefined) {
-            entries = entries.filter((e) => (e.stalenessSeconds === Infinity) === query.neverSynthesized);
+            entries = entries.filter((e) => (e.lastSynthesized === null) === query.neverSynthesized);
         }
         if (query.locked !== undefined) {
             entries = entries.filter((e) => e.locked === query.locked);
@@ -9820,7 +9990,7 @@ function registerMetasRoutes(app, deps) {
             entries = entries.filter((e) => e.stalenessSeconds >= query.staleHours * 3600);
         }
         // Summary (computed from filtered entries)
-        const summary = computeFilteredSummary(entries);
+        const summary = computeSummary(entries, config.depthWeight);
         // Field projection
         const fieldList = query.fields?.split(',');
         const defaultFields = [
@@ -9872,7 +10042,7 @@ function registerMetasRoutes(app, deps) {
                 message: 'Meta path not found: ' + targetPath,
             });
         }
-        const meta = JSON.parse(readFileSync(join(targetNode.metaPath, 'meta.json'), 'utf8'));
+        const meta = JSON.parse(await readFile(join(targetNode.metaPath, 'meta.json'), 'utf8'));
         // Field projection
         const defaultExclude = new Set([
             '_architect',
@@ -9917,6 +10087,25 @@ function registerMetasRoutes(app, deps) {
                 score: Math.round(score * 100) / 100,
             },
         };
+        // Cross-refs status
+        const crossRefsRaw = meta._crossRefs;
+        if (Array.isArray(crossRefsRaw) && crossRefsRaw.length > 0) {
+            response.crossRefs = await Promise.all(crossRefsRaw.map(async (refPath) => {
+                const rp = String(refPath);
+                const refMetaFile = join(rp, '.meta', 'meta.json');
+                try {
+                    const refMeta = JSON.parse(await readFile(refMetaFile, 'utf8'));
+                    return {
+                        path: rp,
+                        status: 'resolved',
+                        hasContent: Boolean(refMeta._content),
+                    };
+                }
+                catch {
+                    return { path: rp, status: 'missing' };
+                }
+            }));
+        }
         // Archive
         if (query.includeArchive) {
             const archiveFiles = listArchiveFiles(targetNode.metaPath);
@@ -9924,10 +10113,10 @@ function registerMetasRoutes(app, deps) {
                 ? query.includeArchive
                 : archiveFiles.length;
             const selected = archiveFiles.slice(-limit).reverse();
-            response.archive = selected.map((af) => {
-                const raw = readFileSync(af, 'utf8');
+            response.archive = await Promise.all(selected.map(async (af) => {
+                const raw = await readFile(af, 'utf8');
                 return projectMeta(JSON.parse(raw));
-            });
+            }));
         }
         return response;
     });
@@ -9978,12 +10167,12 @@ function registerPreviewRoute(app, deps) {
             }
             targetNode = findNode(result.tree, stalestPath);
         }
-        const meta = readMetaJson(targetNode.metaPath);
+        const meta = await readMetaJson(targetNode.metaPath);
         // Scope files
         const { scopeFiles } = await getScopeFiles(targetNode, watcher);
         const structureHash = computeStructureHash(scopeFiles);
         const structureChanged = structureHash !== meta._structureHash;
-        const latestArchive = readLatestArchive(targetNode.metaPath);
+        const latestArchive = await readLatestArchive(targetNode.metaPath);
         const steerChanged = hasSteerChanged(meta._steer, latestArchive?._steer, Boolean(latestArchive));
         const architectTriggered = isArchitectTriggered(meta, structureChanged, steerChanged, config.architectEvery);
         // Delta files
@@ -10034,28 +10223,28 @@ function registerPreviewRoute(app, deps) {
  */
 const seedBodySchema = z.object({
     path: z.string().min(1),
+    crossRefs: z.array(z.string()).optional(),
+    steer: z.string().optional(),
 });
 function registerSeedRoute(app, deps) {
-    app.post('/seed', (request, reply) => {
+    app.post('/seed', async (request, reply) => {
         const body = seedBodySchema.parse(request.body);
-        const metaDir = resolveMetaDir(body.path);
-        if (existsSync(metaDir)) {
+        if (metaExists(body.path)) {
             return reply.status(409).send({
                 error: 'CONFLICT',
                 message: `.meta directory already exists at ${body.path}`,
             });
         }
-        deps.logger.info({ metaDir }, 'creating .meta directory');
-        mkdirSync(metaDir, { recursive: true });
-        const metaJson = { _id: randomUUID() };
-        const metaJsonPath = join(metaDir, 'meta.json');
-        deps.logger.info({ metaJsonPath }, 'writing meta.json');
-        writeFileSync(metaJsonPath, JSON.stringify(metaJson, null, 2) + '\n');
+        deps.logger.info({ path: body.path }, 'seeding .meta directory');
+        const result = await createMeta(body.path, {
+            crossRefs: body.crossRefs,
+            steer: body.steer,
+        });
         return reply.status(201).send({
             status: 'created',
             path: body.path,
-            metaDir,
-            _id: metaJson._id,
+            metaDir: result.metaDir,
+            _id: result._id,
         });
     });
 }
@@ -10504,6 +10693,44 @@ class RuleRegistrar {
     }
 }
 
+/**
+ * Post-registration verification of virtual rule application.
+ *
+ * After rules are registered with the watcher, verifies that .meta/meta.json
+ * files are discoverable via watcher walk (which depends on virtual rules
+ * being applied). Logs a warning if expected metas are not found.
+ *
+ * @module rules/verify
+ */
+/**
+ * Verify that virtual rules are applied to indexed .meta/meta.json files.
+ *
+ * Runs a discovery pass and logs the result. If no metas are found but
+ * the filesystem likely has some, logs a warning suggesting reindex.
+ *
+ * @param watcher - WatcherClient for discovery.
+ * @param logger - Logger for reporting results.
+ * @returns Number of metas discovered.
+ */
+async function verifyRuleApplication(watcher, logger) {
+    try {
+        const metaPaths = await discoverMetas(watcher);
+        if (metaPaths.length === 0) {
+            logger.warn({ count: 0 }, 'Post-registration verification: no .meta/meta.json files found via watcher walk. ' +
+                'Virtual rules may not be applied to indexed files. ' +
+                'If metas exist, a path-scoped reindex may be needed.');
+        }
+        else {
+            logger.info({ count: metaPaths.length }, 'Post-registration verification: metas discoverable');
+        }
+        return metaPaths.length;
+    }
+    catch (err) {
+        logger.warn({ err: err instanceof Error ? err.message : String(err) }, 'Post-registration verification failed (watcher may be unavailable)');
+        return 0;
+    }
+}
+
 /**
  * Minimal Fastify HTTP server for jeeves-meta service.
  *
@@ -10799,7 +11026,7 @@ async function startService(config, configPath) {
                     cycleTokens += evt.tokens;
                 }
                 await progress.report(evt);
-            });
+            }, logger);
             // orchestrate() always returns exactly one result
             const result = results[0];
             const durationMs = Date.now() - startMs;
@@ -10851,11 +11078,15 @@ async function startService(config, configPath) {
     }
     // Start scheduler
     scheduler.start();
-    // Rule registration (fire-and-forget with retries)
+    // Rule registration (fire-and-forget with retries) + post-registration verification
     const registrar = new RuleRegistrar(config, logger, watcher);
     scheduler.setRegistrar(registrar);
     routeDeps.registrar = registrar;
-    void registrar.register();
+    void registrar.register().then(() => {
+        if (registrar.isRegistered) {
+            void verifyRuleApplication(watcher, logger);
+        }
+    });
     // Periodic watcher health check (independent of scheduler)
     const healthCheck = new WatcherHealthCheck({
         watcherUrl: config.watcherUrl,
@@ -10864,26 +11095,52 @@ async function startService(config, configPath) {
         logger,
     });
     healthCheck.start();
-    // Config hot-reload (gap #12)
+    // Config hot-reload (gap #12, expanded #32)
+    // Fields requiring a service restart to take effect
+    const restartRequiredFields = [
+        'port',
+        'host',
+        'watcherUrl',
+        'gatewayUrl',
+        'gatewayApiKey',
+        'defaultArchitect',
+        'defaultCritic',
+    ];
     if (configPath) {
         watchFile(configPath, { interval: 5000 }, () => {
             try {
                 const newConfig = loadServiceConfig(configPath);
-                // Hot-reloadable fields: schedule, reportChannel, logging level
+                // Warn about restart-required field changes
+                for (const field of restartRequiredFields) {
+                    const oldVal = config[field];
+                    const newVal = newConfig[field];
+                    if (oldVal !== newVal) {
+                        logger.warn({ field, oldValue: oldVal, newValue: newVal }, 'Config field changed but requires restart to take effect');
+                    }
+                }
+                // Hot-reload schedule
                 if (newConfig.schedule !== config.schedule) {
                     scheduler.updateSchedule(newConfig.schedule);
                     logger.info({ schedule: newConfig.schedule }, 'Schedule hot-reloaded');
                 }
-                if (newConfig.reportChannel !== config.reportChannel) {
-                    // Mutate shared config reference for progress reporter
-                    config.reportChannel =
-                        newConfig.reportChannel;
-                    logger.info({ reportChannel: newConfig.reportChannel }, 'reportChannel hot-reloaded');
-                }
+                // Hot-reload logging level
                 if (newConfig.logging.level !== config.logging.level) {
                     logger.level = newConfig.logging.level;
                     logger.info({ level: newConfig.logging.level }, 'Log level hot-reloaded');
                 }
+                // Merge all non-restart-required fields into shared config ref.
+                // newConfig is Zod-parsed, so removed fields get defaults — no deletion needed.
+                const restartSet = new Set(restartRequiredFields);
+                for (const key of Object.keys(newConfig)) {
+                    if (restartSet.has(key) || key === 'logging')
+                        continue;
+                    const oldVal = config[key];
+                    const newVal = newConfig[key];
+                    if (JSON.stringify(oldVal) !== JSON.stringify(newVal)) {
+                        config[key] = newVal;
+                        logger.info({ field: key }, 'Config field hot-reloaded');
+                    }
+                }
             }
             catch (err) {
                 logger.warn({ err }, 'Config hot-reload failed');