@karmaniverous/jeeves-meta 0.9.0 → 0.10.1

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

@@ -1,14 +1,15 @@
 #!/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';
 import pino from 'pino';
+import Handlebars from 'handlebars';
 import { Cron } from 'croner';
 import vm from 'vm';
 import require$$0$3 from 'path';
@@ -52,10 +53,10 @@ const metaConfigSchema = z.object({
     criticTimeout: z.number().int().min(30).default(300),
     /** Thinking level for spawned synthesis sessions. */
     thinking: z.string().default('low'),
-    /** Resolved architect system prompt text. */
-    defaultArchitect: z.string(),
-    /** Resolved critic system prompt text. */
-    defaultCritic: z.string(),
+    /** Resolved architect system prompt text. Falls back to built-in default. */
+    defaultArchitect: z.string().optional(),
+    /** Resolved critic system prompt text. Falls back to built-in default. */
+    defaultCritic: z.string().optional(),
     /** Skip unchanged candidates, bump _generatedAt. */
     skipUnchanged: z.boolean().default(true),
     /** Watcher metadata properties applied to live .meta/meta.json files. */
@@ -72,6 +73,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 +98,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 +353,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 +373,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 +396,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 +406,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 +671,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 +784,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 +811,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 +828,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 +932,18 @@ function filterInScope(node, files) {
 /**
  * Get all files in scope for a meta node via watcher walk.
  */
-async function getScopeFiles(node, watcher) {
-    const allFiles = await watcher.walk([`${node.ownerPath}/**`]);
-    return {
-        scopeFiles: filterInScope(node, allFiles),
-        allFiles,
-    };
+async function getScopeFiles(node, watcher, logger) {
+    const walkStart = Date.now();
+    const rawFiles = await watcher.walk([`${node.ownerPath}/**`]);
+    const allFiles = rawFiles.map(normalizePath);
+    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.
@@ -1197,6 +1235,23 @@ function createLogger(config) {
     return pino({ level });
 }
 
+/**
+ * Built-in default prompts for the synthesis pipeline.
+ *
+ * Prompts ship as .md files bundled into dist/prompts/ via rollup-plugin-copy.
+ * Loaded at runtime relative to the compiled module location.
+ *
+ * Users can override via `defaultArchitect` / `defaultCritic` in the service
+ * config. Most installations should use the built-in defaults.
+ *
+ * @module prompts
+ */
+const promptDir = dirname(fileURLToPath(import.meta.url));
+/** Built-in default architect prompt. */
+const DEFAULT_ARCHITECT_PROMPT = readFileSync(join(promptDir, 'architect.md'), 'utf8');
+/** Built-in default critic prompt. */
+const DEFAULT_CRITIC_PROMPT = readFileSync(join(promptDir, 'critic.md'), 'utf8');
+
 /**
  * Build the MetaContext for a synthesis cycle.
  *
@@ -1236,9 +1291,9 @@ function condenseScopeFiles(files, maxIndividual = 30) {
  * @param metaJsonPath - Absolute path to a meta.json file.
  * @returns The `_content` string, or null if missing/unreadable.
  */
-function readMetaContent(metaJsonPath) {
+async function readMetaContent(metaJsonPath) {
     try {
-        const raw = readFileSync(metaJsonPath, 'utf8');
+        const raw = await readFile(metaJsonPath, 'utf8');
         const meta = JSON.parse(raw);
         return meta._content ?? null;
     }
@@ -1254,25 +1309,43 @@ function readMetaContent(metaJsonPath) {
  * @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) {
-        childMetas[child.ownerPath] = readMetaContent(join(child.metaPath, 'meta.json'));
+    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
+    // 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);
-        crossRefMetas[refPath] = readMetaContent(join(refPath, '.meta', 'meta.json'));
+        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);
@@ -1293,8 +1366,37 @@ async function buildContextPackage(node, meta, watcher) {
 /**
  * Build task prompts for each synthesis step.
  *
+ * Prompts are compiled as Handlebars templates with access to config,
+ * meta, and scope context. The architect can write template expressions
+ * into its _builder output; these resolve when the builder task is compiled.
+ *
  * @module orchestrator/buildTask
  */
+/** Build the template context from synthesis inputs. */
+function buildTemplateContext(ctx, meta, config) {
+    return {
+        config,
+        meta,
+        scope: {
+            fileCount: ctx.scopeFiles.length,
+            deltaCount: ctx.deltaFiles.length,
+            childCount: Object.keys(ctx.childMetas).length,
+            crossRefCount: Object.keys(ctx.crossRefMetas).length,
+        },
+    };
+}
+/**
+ * Compile a string as a Handlebars template with the given context.
+ * Returns the original string unchanged if compilation fails.
+ */
+function compileTemplate(text, context) {
+    try {
+        return Handlebars.compile(text, { noEscape: true })(context);
+    }
+    catch {
+        return text;
+    }
+}
 /** Append a keyed record of meta outputs as subsections, if non-empty. */
 function appendMetaSections(sections, heading, metas) {
     if (Object.keys(metas).length === 0)
@@ -1341,7 +1443,7 @@ function appendSharedSections(sections, ctx, options) {
  */
 function buildArchitectTask(ctx, meta, config) {
     const sections = [
-        meta._architect ?? config.defaultArchitect,
+        meta._architect ?? config.defaultArchitect ?? DEFAULT_ARCHITECT_PROMPT,
         '',
         '## SCOPE',
         `Path: ${ctx.path}`,
@@ -1359,7 +1461,7 @@ function buildArchitectTask(ctx, meta, config) {
     if (ctx.archives.length > 0) {
         sections.push('', '## ARCHIVE HISTORY', `${ctx.archives.length.toString()} previous synthesis snapshots available in .meta/archive/.`, 'Review these to understand how the synthesis has evolved over time.');
     }
-    return sections.join('\n');
+    return compileTemplate(sections.join('\n'), buildTemplateContext(ctx, meta, config));
 }
 /**
  * Build the builder task prompt.
@@ -1387,7 +1489,7 @@ function buildBuilderTask(ctx, meta, config) {
         feedbackHeading: '## FEEDBACK FROM CRITIC',
     });
     sections.push('', '## OUTPUT FORMAT', '', 'Respond with ONLY a JSON object. No explanation, no markdown fences, no text before or after.', '', 'Required schema:', '{', '  "type": "object",', '  "required": ["_content"],', '  "properties": {', '    "_content": { "type": "string", "description": "Markdown narrative synthesis" },', '    "_state": { "description": "Opaque state object for progressive work across cycles" }', '  },', '  "additionalProperties": true', '}', '', 'Add any structured fields that capture important facts about this entity', '(e.g. status, risks, dependencies, metrics). Use descriptive key names without underscore prefix.', 'The _content field is the only required key — everything else is domain-driven.', '_state is optional: set it to carry state across synthesis cycles for progressive work.', '', 'DIAGRAMS: When diagrams would aid understanding, use PlantUML in fenced code blocks (```plantuml).', 'PlantUML is rendered natively by the serving infrastructure. NEVER use ASCII art diagrams.');
-    return sections.join('\n');
+    return compileTemplate(sections.join('\n'), buildTemplateContext(ctx, meta, config));
 }
 /**
  * Build the critic task prompt.
@@ -1399,7 +1501,7 @@ function buildBuilderTask(ctx, meta, config) {
  */
 function buildCriticTask(ctx, meta, config) {
     const sections = [
-        meta._critic ?? config.defaultCritic,
+        meta._critic ?? config.defaultCritic ?? DEFAULT_CRITIC_PROMPT,
         '',
         '## SYNTHESIS TO EVALUATE',
         meta._content ?? '(No content produced)',
@@ -1415,7 +1517,7 @@ function buildCriticTask(ctx, meta, config) {
         includeCrossRefs: false,
     });
     sections.push('', '## OUTPUT FORMAT', 'Return your evaluation as Markdown text. Be specific and actionable.');
-    return sections.join('\n');
+    return compileTemplate(sections.join('\n'), buildTemplateContext(ctx, meta, config));
 }
 
 /**
@@ -1444,8 +1546,8 @@ 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(),
     /**
@@ -1538,10 +1640,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,
@@ -1614,7 +1716,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;
 }
 
@@ -1854,11 +1956,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,
@@ -1877,10 +1979,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;
 }
@@ -1993,14 +2095,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
@@ -2014,7 +2114,7 @@ function attemptTimeoutRecovery(opts) {
                 code: 'TIMEOUT',
                 message: err.message,
             };
-            finalizeCycle({
+            await finalizeCycle({
                 metaPath,
                 current: currentMeta,
                 config,
@@ -2045,12 +2145,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;
@@ -2062,6 +2162,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?.({
@@ -2090,16 +2200,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,
@@ -2141,7 +2246,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,
@@ -2154,16 +2259,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,
         });
@@ -2202,16 +2302,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,
@@ -2243,21 +2338,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
@@ -2293,9 +2392,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;
@@ -2308,8 +2407,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
@@ -2329,7 +2428,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];
 }
 
@@ -2348,14 +2447,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);
@@ -2434,6 +2534,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.
@@ -2531,6 +2748,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);
@@ -9786,53 +10015,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);
@@ -9847,7 +10029,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);
@@ -9856,7 +10038,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 = [
@@ -9908,7 +10090,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',
@@ -9956,13 +10138,11 @@ function registerMetasRoutes(app, deps) {
         // Cross-refs status
         const crossRefsRaw = meta._crossRefs;
         if (Array.isArray(crossRefsRaw) && crossRefsRaw.length > 0) {
-            response.crossRefs = crossRefsRaw.map((refPath) => {
+            response.crossRefs = await Promise.all(crossRefsRaw.map(async (refPath) => {
                 const rp = String(refPath);
                 const refMetaFile = join(rp, '.meta', 'meta.json');
-                if (!existsSync(refMetaFile))
-                    return { path: rp, status: 'missing' };
                 try {
-                    const refMeta = JSON.parse(readFileSync(refMetaFile, 'utf8'));
+                    const refMeta = JSON.parse(await readFile(refMetaFile, 'utf8'));
                     return {
                         path: rp,
                         status: 'resolved',
@@ -9972,7 +10152,7 @@ function registerMetasRoutes(app, deps) {
                 catch {
                     return { path: rp, status: 'missing' };
                 }
-            });
+            }));
         }
         // Archive
         if (query.includeArchive) {
@@ -9981,10 +10161,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;
     });
@@ -10035,12 +10215,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
@@ -10092,30 +10272,27 @@ 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() };
-        if (body.crossRefs !== undefined)
-            metaJson._crossRefs = body.crossRefs;
-        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,
         });
     });
 }
@@ -10564,6 +10741,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.
  *
@@ -10859,7 +11074,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;
@@ -10911,11 +11126,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,
@@ -10924,26 +11143,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');