@nusoft/nuos-build-catalogue 0.33.1 → 0.35.1

package/README.md

@@ -14,7 +14,7 @@ The embedder is selected via `NUOS_CATALOGUE_EMBEDDER`:
 
 | Value | Provider | Default model | Dimensions | Notes |
 |---|---|---|---|---|
-| `ollama` (default) | Local Ollama | `qwen3-embedding:8b` | 4096 | **Sovereignty by default.** No network egress. Override the model with `NUOS_CATALOGUE_OLLAMA_MODEL=qwen3-embedding:4b` (2560 dims) or `qwen3-embedding:0.6b` (1024 dims) for smaller boxes. Needs `ollama serve` running and the model pulled (`ollama pull qwen3-embedding:8b`). |
+| `ollama` (default) | Local Ollama | `qwen3-embedding:0.6b` | 1024 | **Sovereignty by default.** No network egress. The 0.6b default (~600 MB) runs on any modern laptop, including CPU-only. For better recall on a machine with headroom, raise fidelity with `NUOS_CATALOGUE_OLLAMA_MODEL=qwen3-embedding:4b` (2560 dims, ~2.5 GB) or `qwen3-embedding:8b` (4096 dims, ~4.7 GB). Needs `ollama serve` running and the model pulled (`ollama pull qwen3-embedding:0.6b`). |
 | `vertex` | Google Vertex | `text-embedding-005` | 768 | Cloud Google. Needs `GOOGLE_CLOUD_PROJECT` plus a Vertex access token (set `GOOGLE_VERTEX_ACCESS_TOKEN`, or have `gcloud` on PATH and run `gcloud auth application-default login`). |
 | `openai` | OpenAI | `text-embedding-3-small` | 1536 | Cloud OpenAI. Needs `OPENAI_API_KEY`. |
 | `stub` | Hash-based, no API | — | 384 | Tests + dev only. Results are noisy. |
@@ -26,9 +26,9 @@ Switching embedder (or model variant) requires a full reindex (`rm -rf .nuos-cat
 ```bash
 # Pre-flight (one time):
 ollama serve                          # in another shell
-ollama pull qwen3-embedding:8b        # ~4.7 GB download
+ollama pull qwen3-embedding:0.6b      # ~600 MB download
 
-# Index the catalogue (first time — takes ~20 min on 8b)
+# Index the catalogue (first time re-embeds everything; later runs only re-embed changed files)
 npm run index
 
 # Search

package/dist/cli.js

@@ -436,6 +436,15 @@ Usage:
   nuos-catalogue memory    store     --value="..." [--wu=wu-007] [--agent=architect] [--key="label"]
   nuos-catalogue memory    search    --query="..." [--limit=N]   [--wu=wu-007]       [--agent=architect]
 
+  nuos-catalogue state      compile   [--dry-run] [--state-md=<path>]
+                          (WU 113b — recompile STATE.md generated regions from canonical store;
+                           splices metadata / what-is-next / open-questions / decisions / risks /
+                           health-check regions; preserves authored prose byte-for-byte)
+  nuos-catalogue state      drift-check [--state-md=<path>]
+                          (WU 113b Stage B — check whether STATE.md generated regions match
+                           canonical state; exit 0 on clean / no-regions / can't-run;
+                           exit 1 ONLY on confirmed generated-region drift; called by pre-commit hook)
+
   nuos-catalogue end-of-session
                           (WU 112 — verify-and-gate: checks the nine end-of-session protocol steps
                            against disk facts; prints a per-check report; exits non-zero on a blocked
@@ -657,6 +666,45 @@ async function main() {
             process.exit(result.exitCode);
             break;
         }
+        case 'state': {
+            // `state compile`      — regenerate the generated regions of STATE.md (WU 113b / D132).
+            // `state drift-check`  — check for generated-region drift (Stage B; called by pre-commit hook).
+            const sub = args.positional[0];
+            const buildRoot = resolveBuildRoot(args.flags['build-root']);
+            const workflowsPath = resolveWorkflowsPath(buildRoot, args.flags['workflows']);
+            if (sub === 'compile') {
+                const { cmdStateCompile } = await import('./commands/state-compile.js');
+                const store = await openWorkflowStore(workflowsPath);
+                const result = await cmdStateCompile(store, {
+                    buildRoot,
+                    stateMdPath: args.flags['state-md'] ? String(args.flags['state-md']) : undefined,
+                    dryRun: Boolean(args.flags['dry-run']),
+                });
+                if (result.output)
+                    console.log(result.output);
+                process.exit(result.exitCode);
+            }
+            else if (sub === 'drift-check') {
+                const { cmdStateDriftCheck } = await import('./commands/state-compile.js');
+                const store = await openWorkflowStore(workflowsPath);
+                const result = await cmdStateDriftCheck(store, {
+                    buildRoot,
+                    stateMdPath: args.flags['state-md'] ? String(args.flags['state-md']) : undefined,
+                });
+                // Drift-check output: clean/skipped messages go to stderr (informational); drifted goes to stderr too.
+                if (result.output)
+                    process.stderr.write(result.output + '\n');
+                process.exit(result.exitCode);
+            }
+            else {
+                console.error(`unknown state subcommand: ${sub ?? '(none)'}`);
+                console.error('available:');
+                console.error('  state compile     [--dry-run] [--state-md=<path>] [--build-root=<dir>] [--workflows=<file>]');
+                console.error('  state drift-check [--state-md=<path>] [--build-root=<dir>] [--workflows=<file>]');
+                process.exit(1);
+            }
+            break;
+        }
         case 'start-of-session': {
             // Reserved handle — body in a follow-up WU.
             console.error('start-of-session: not yet implemented (WU 112 reserves the handle; body in a follow-up WU).');

package/dist/commands/end-of-session.js

@@ -22,6 +22,7 @@
  */
 import { stat, readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
+import { cmdStateCompile } from './state-compile.js';
 const BUILD_MAINTAINER = {
     kind: 'staff',
     id: 'build-maintainer',
@@ -46,7 +47,7 @@ export async function cmdEndOfSession(store, runtime, args) {
     }
     // Gather disk facts — this is the only place filesystem access happens
     // (the workflow itself is pure).
-    const catalogueFacts = await gatherFacts(args.buildRoot, activeWuHandle, sessionStartIso, today);
+    const catalogueFacts = await gatherFacts(args.buildRoot, activeWuHandle, sessionStartIso, today, store);
     // Check for an existing (incomplete) session.end:<date> record.
     const existingHandle = `session.end:${today}`;
     const existingRecord = store.get(existingHandle);
@@ -71,6 +72,7 @@ export async function cmdEndOfSession(store, runtime, args) {
                     'capture_open_questions',
                     'capture_risks',
                     'update_work_units_index',
+                    'recompile_state_md',
                     'update_state_md',
                     'write_session_log',
                     'confirm_no_loss',
@@ -127,7 +129,7 @@ export async function cmdEndOfSession(store, runtime, args) {
 // ---------------------------------------------------------------------------
 // Disk fact gathering — the only place fs access happens
 // ---------------------------------------------------------------------------
-async function gatherFacts(buildRoot, activeWuHandle, sessionStartIso, sessionDate) {
+async function gatherFacts(buildRoot, activeWuHandle, sessionStartIso, sessionDate, store) {
     const sessionStartMs = new Date(sessionStartIso).getTime();
     // Step 1: WU notes
     const { wuNotesTouched, wuNotesHasTodayHeading } = await checkWuNotes(buildRoot, activeWuHandle, sessionStartMs, sessionDate);
@@ -137,6 +139,10 @@ async function gatherFacts(buildRoot, activeWuHandle, sessionStartIso, sessionDa
     const risksParity = await checkRisksParity(buildRoot);
     // Step 5: work-units index
     const doneMoveOk = await checkWorkUnitsIndex(buildRoot);
+    // Step 5.5 (D132): recompile the generated regions of STATE.md.
+    // This is the orchestrate-and-write step sanctioned by D132 for generated regions.
+    // It must not fail the session if STATE.md has no sentinel regions yet (pre-cutover).
+    const { stateMdRecompileResult, stateMdRecompileDetail } = await recompileStateMd(buildRoot, store);
     // Step 6: STATE.md
     const { stateMdTouched, stateMdLastUpdated, stateMdLastSessionResolves } = await checkStateMd(buildRoot, sessionStartMs, sessionDate);
     // Step 7: session log
@@ -148,6 +154,8 @@ async function gatherFacts(buildRoot, activeWuHandle, sessionStartIso, sessionDa
         questionsParity,
         risksParity,
         doneMoveOk,
+        stateMdRecompileResult,
+        stateMdRecompileDetail,
         stateMdTouched,
         stateMdLastUpdated,
         stateMdLastSessionResolves,
@@ -294,6 +302,44 @@ async function checkRisksParity(buildRoot) {
     // This check is present for forward-compat when risks get individual files.
     return { filesWithoutRow: [], rowsWithoutFile: [] };
 }
+/**
+ * Recompile the generated regions of STATE.md (D132 / D130: orchestrate-and-write
+ * for the generated regions is sanctioned by D132; authored prose is never touched).
+ *
+ * Fail-open contract (same as `cmdStateDriftCheck`):
+ *   - 'skipped' when STATE.md has no sentinel regions yet (pre-cutover) — ok
+ *   - 'ok'      when the recompile succeeded (or was already current)
+ *   - 'error'   when the compile command returned non-zero (adapter error, splice error)
+ *
+ * A 'skipped' result is treated as passing by the pack workflow so that
+ * end-of-session is not broken for catalogues that haven't completed Stage B cutover.
+ */
+async function recompileStateMd(buildRoot, store) {
+    try {
+        const result = await cmdStateCompile(store, { buildRoot });
+        if (result.exitCode === 0) {
+            return { stateMdRecompileResult: 'ok', stateMdRecompileDetail: result.output?.trim() };
+        }
+        // Non-zero exit from cmdStateCompile — check if it's the missing-sentinel case (pre-cutover).
+        // The missing-sentinel output contains the specific wording from the command.
+        if (result.output?.includes('sentinel regions are absent')) {
+            return {
+                stateMdRecompileResult: 'skipped',
+                stateMdRecompileDetail: 'sentinel regions absent — pre-cutover',
+            };
+        }
+        return {
+            stateMdRecompileResult: 'error',
+            stateMdRecompileDetail: result.output?.trim(),
+        };
+    }
+    catch (err) {
+        return {
+            stateMdRecompileResult: 'error',
+            stateMdRecompileDetail: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
 async function checkWorkUnitsIndex(buildRoot) {
     const indexPath = path.join(buildRoot, 'work-units', '_index.md');
     const content = await fileContent(indexPath);
@@ -349,7 +395,9 @@ async function checkStateMd(buildRoot, sessionStartMs, sessionDate) {
     const stateMdTouched = mtime ? mtime.getTime() > sessionStartMs : false;
     const content = await fileContent(stateMdPath);
     let stateMdLastUpdated = '';
-    let stateMdLastSessionResolves = false;
+    // Renamed from stateMdLastSessionResolves → stateMdLastSessionPresent (WU 113b).
+    // The field checks presence of a non-empty "Last session" row, not link resolution.
+    let stateMdLastSessionPresent = false;
     if (content) {
         // Fix 1 (WU 112 fix-pass): accept all three "Last updated" shapes:
         //   table-row: | Last updated | 2026-05-31 (**Session 115 — ...**) ... |
@@ -370,10 +418,14 @@ async function checkStateMd(buildRoot, sessionStartMs, sessionDate) {
         if (sessionLineMatch) {
             // The row is non-empty if it contains more than just the label itself.
             const rowText = sessionLineMatch[0].replace(/Last session/i, '').replace(/[|:\s]/g, '');
-            stateMdLastSessionResolves = rowText.length > 0;
+            stateMdLastSessionPresent = rowText.length > 0;
         }
     }
-    return { stateMdTouched, stateMdLastUpdated, stateMdLastSessionResolves };
+    // Return under the pack's EndOfSessionFacts field name (stateMdLastSessionResolves)
+    // — the internal variable was renamed to stateMdLastSessionPresent above to clarify
+    // the semantics (presence check, not link-resolution). The published interface is
+    // unchanged so the pack type is not broken.
+    return { stateMdTouched, stateMdLastUpdated, stateMdLastSessionResolves: stateMdLastSessionPresent };
 }
 async function checkSessionLog(buildRoot, sessionDate) {
     const sessionsDir = path.join(buildRoot, 'sessions');
@@ -406,15 +458,16 @@ function formatReport(payload, today, resumedFrom, dryRun) {
     lines.push('══════════════════════════════════════════════════════════════════════');
     lines.push('');
     const STEP_LABELS = {
-        update_active_wu_notes: 'Step 1 — WU notes updated',
-        capture_decisions: 'Step 2 — decisions captured',
-        capture_open_questions: 'Step 3 — open questions captured',
-        capture_risks: 'Step 4 — risks captured',
-        update_work_units_index: 'Step 5 — work-units index updated',
-        update_state_md: 'Step 6 — STATE.md updated',
-        write_session_log: 'Step 7 — session log written',
-        confirm_no_loss: 'Step 8 — confirm-no-loss gate',
-        report: 'Step 9 — report',
+        update_active_wu_notes: 'Step 1  — WU notes updated',
+        capture_decisions: 'Step 2  — decisions captured',
+        capture_open_questions: 'Step 3  — open questions captured',
+        capture_risks: 'Step 4  — risks captured',
+        update_work_units_index: 'Step 5  — work-units index updated',
+        recompile_state_md: 'Step 5b — STATE.md generated regions recompiled (D132)',
+        update_state_md: 'Step 6  — STATE.md updated',
+        write_session_log: 'Step 7  — session log written',
+        confirm_no_loss: 'Step 8  — confirm-no-loss gate',
+        report: 'Step 9  — report',
     };
     for (const [stepId, state] of Object.entries(payload.steps)) {
         const label = STEP_LABELS[stepId] ?? stepId;

package/dist/commands/memory.d.ts

@@ -4,8 +4,9 @@
  *
  * Cross-agent memory: every agent in a swarm can write findings here and
  * any future agent (in this run or a later one) can retrieve them by
- * semantic query. Uses the same NuVector store as the catalogue index,
- * distinguished by kind: 'agent_memory'.
+ * semantic query. Uses its own NuVector store file (`memory.nv`), separate
+ * from the doc-search index (`index.nv`), so that the ~40s background
+ * reindex never locks out memory writes. See D131.
  *
  * CLI:
  *   memory store  --value="..."  [--wu=wu-007] [--agent=architect] [--key="label"]
@@ -18,6 +19,9 @@ export interface MemoryStoreOptions {
     key?: string;
     cwd?: string;
     buildRoot?: string | boolean;
+    /** Override for the memory store path (defaults to `<index-dir>/memory.nv`). */
+    memory?: string | boolean;
+    /** @deprecated Kept for callers that pass `index` — resolved as `memory` for memory commands. */
     index?: string | boolean;
 }
 export interface MemorySearchOptions {
@@ -27,6 +31,9 @@ export interface MemorySearchOptions {
     agent?: string;
     cwd?: string;
     buildRoot?: string | boolean;
+    /** Override for the memory store path (defaults to `<index-dir>/memory.nv`). */
+    memory?: string | boolean;
+    /** @deprecated Kept for callers that pass `index` — resolved as `memory` for memory commands. */
     index?: string | boolean;
 }
 export interface MemoryHit {

package/dist/commands/memory.js

@@ -4,21 +4,167 @@
  *
  * Cross-agent memory: every agent in a swarm can write findings here and
  * any future agent (in this run or a later one) can retrieve them by
- * semantic query. Uses the same NuVector store as the catalogue index,
- * distinguished by kind: 'agent_memory'.
+ * semantic query. Uses its own NuVector store file (`memory.nv`), separate
+ * from the doc-search index (`index.nv`), so that the ~40s background
+ * reindex never locks out memory writes. See D131.
  *
  * CLI:
  *   memory store  --value="..."  [--wu=wu-007] [--agent=architect] [--key="label"]
  *   memory search --query="..."  [--limit=N]   [--wu=wu-007]       [--agent=architect]
  */
 import { randomUUID } from 'node:crypto';
-import { resolveBuildRoot, resolveIndexPath } from '../path-resolution.js';
+import { existsSync, unlinkSync, writeFileSync } from 'node:fs';
+import { resolveBuildRoot, resolveIndexPath, resolveMemoryPath } from '../path-resolution.js';
+// resolveIndexPath is used only as the migration *source* (legacy index.nv),
+// not as the live memory path (which is resolved via resolveMemoryPath).
 // NuVector's MemoryRecordKind union doesn't include a swarm-specific kind yet.
 // 'workflow_provenance' is the closest semantic match — agent memories are
 // provenance of the swarm workflow. NuFlow isn't wired (harness.runtime.nuflow
 // is null) so there's no collision today; records are further distinguished by
 // the presence of an `agent_role` metadata field (absent on NuFlow provenance).
 const MEMORY_KIND = 'workflow_provenance';
+/**
+ * One-time idempotent migration: copy existing agent-memory records
+ * (kind `workflow_provenance` with an `agent_role` metadata field) from
+ * the legacy `index.nv` into the new `memory.nv`. Triggered lazily the
+ * first time a memory command opens the store (i.e. when `memory.nv` does
+ * not yet exist). Once `memory.nv` exists this function is a no-op.
+ *
+ * Decision on delete-vs-leave: we leave migrated records in `index.nv`.
+ * They are dead weight there — `memory search` reads only `memory.nv`,
+ * and the doc reindex upserts only doc-kind records — so leaving them
+ * causes no observable problem. Deletion via the store's `DeletionQuery`
+ * API would need the id list; the extra complexity buys nothing for a
+ * handful of records.
+ *
+ * Embeddings are copied verbatim via `fetch(ids)` — no re-embedding.
+ * If `index.nv` does not exist yet (fresh project), migration is skipped.
+ *
+ * Atomicity: uses a sentinel file (`memory.nv.migrating`) written before the
+ * migration opens `memory.nv` and deleted after a successful close. If the
+ * process dies mid-migration, the next run sees both files and retries.
+ *
+ * INVARIANT — never `unlinkSync(memoryPath)` then `openStore(memoryPath)` in
+ * the same process. NuVector's NAPI in-process inode registry tracks handles
+ * by inode; a same-process unlink+reopen materialises the store in-memory only
+ * (the file never appears on disk), silently losing all data on process exit.
+ * The only permitted `unlinkSync(memoryPath)` is the corrupt-open-failure guard
+ * at the bottom, which always re-throws immediately — the store is never
+ * reopened in the same process after that unlink.
+ *
+ * In the interrupted-migration path (memory.nv + sentinel both present) we
+ * therefore open the existing partial `memory.nv` directly. `upsertBatch` is
+ * idempotent by id, so re-writing the same records into a partial store just
+ * completes it, with no phantom-materialisation risk.
+ */
+async function migrateMemoryRecordsIfNeeded(indexPath, memoryPath, dimensions) {
+    const sentinelPath = `${memoryPath}.migrating`;
+    // Complete gate: memory.nv exists with no sentinel → done (either a clean
+    // migration or a store created by a normal memory write). Early return.
+    if (existsSync(memoryPath) && !existsSync(sentinelPath))
+        return;
+    // Fresh project: no legacy index to migrate from. Clear any stray sentinel
+    // (shouldn't exist, but be tidy) and return; the caller's openStore will
+    // create memory.nv fresh on its own write.
+    if (!existsSync(indexPath)) {
+        if (existsSync(sentinelPath)) {
+            try {
+                unlinkSync(sentinelPath);
+            }
+            catch { /* ignore — best-effort */ }
+        }
+        return;
+    }
+    const { openStore, TENANT } = await import('../store/open.js');
+    // Write the sentinel before opening memory.nv. If the process dies after
+    // this point, the next run sees both files (or just the sentinel) and
+    // falls through to the (re)migration path below.
+    try {
+        writeFileSync(sentinelPath, '');
+    }
+    catch { /* non-fatal; best-effort */ }
+    try {
+        // Read from index.nv. Hold the store open for both retrieveContext and
+        // fetch — a single open avoids a close→reopen timing window.
+        const srcStore = await openStore({ storagePath: indexPath, dimensions });
+        let fullRecords;
+        try {
+            const zeroEmbedding = new Float32Array(dimensions);
+            const result = await srcStore.retrieveContext({
+                embedding: zeroEmbedding,
+                tenant: TENANT,
+                topK: 10_000,
+                filters: { kind: MEMORY_KIND },
+                scoreThreshold: 0,
+            });
+            const items = (result?.items ?? []);
+            // Filter to agent-memory records (presence of `agent_role` metadata).
+            const agentMemoryRefs = items
+                .filter((item) => {
+                const meta = item.metadata;
+                return meta !== undefined && 'agent_role' in meta;
+            })
+                .map((item) => item.ref);
+            fullRecords = agentMemoryRefs.length > 0
+                ? await srcStore.fetch(agentMemoryRefs)
+                : [];
+        }
+        finally {
+            await srcStore.close();
+        }
+        // Open memory.nv — create fresh (first run) or open the existing partial
+        // file (interrupted run). Do NOT unlink first: same-process unlink+reopen
+        // triggers the NAPI phantom-materialisation bug (see invariant above).
+        // upsertBatch is idempotent by id, so replaying into a partial store is safe.
+        let dstStore;
+        try {
+            dstStore = await openStore({ storagePath: memoryPath, dimensions });
+        }
+        catch (openErr) {
+            // openStore itself threw — the partial file is genuinely corrupt.
+            // Unlink it so a future process gets a clean create, leave the sentinel
+            // so that future run still enters the (re)migration path, then rethrow.
+            // NEVER reopen memoryPath in this process after this unlink.
+            if (existsSync(memoryPath)) {
+                try {
+                    unlinkSync(memoryPath);
+                }
+                catch { /* ignore */ }
+            }
+            throw openErr;
+        }
+        try {
+            if (fullRecords.length > 0) {
+                await dstStore.upsertBatch(fullRecords);
+            }
+            // If there are no agent-memory records, the store is opened-and-closed
+            // empty. That materialises memory.nv on disk so existsSync is true and
+            // the gate is stable — memory search never falls through to re-read
+            // index.nv on subsequent calls.
+        }
+        finally {
+            await dstStore.close();
+        }
+        // Migration complete. Remove sentinel so the gate sees memory.nv alone.
+        try {
+            unlinkSync(sentinelPath);
+        }
+        catch { /* ignore — best-effort */ }
+    }
+    catch (err) {
+        // Any failure other than the corrupt-open case above (e.g. F2 lock on
+        // index.nv): clean up the sentinel so the next call retries from scratch.
+        // Do NOT unlink memoryPath here — if it was opened successfully before the
+        // failure, it's a valid partial store that the next run can complete via
+        // upsertBatch. Unlinking it would trigger the phantom-materialisation bug
+        // on re-entry in the same process.
+        try {
+            unlinkSync(sentinelPath);
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
+}
 export async function cmdMemoryStore(opts) {
     const { value, wu, agent, key } = opts;
     if (!value || value.trim().length === 0) {
@@ -28,9 +174,16 @@ export async function cmdMemoryStore(opts) {
     const { selectEmbedderFromEnv } = await import('../embedder/select.js');
     const { openStore, TENANT } = await import('../store/open.js');
     const buildRoot = resolveBuildRoot(opts.buildRoot, { cwd: opts.cwd ?? process.cwd() });
-    const indexPath = resolveIndexPath(buildRoot, opts.index);
+    // Resolve the memory-specific path (memory.nv), falling back to the
+    // legacy `index` flag for callers that pass it, then the default.
+    const memoryFlag = opts.memory ?? opts.index;
+    const memoryPath = resolveMemoryPath(buildRoot, memoryFlag);
+    const indexPath = resolveIndexPath(buildRoot, undefined);
     const embedder = await selectEmbedderFromEnv();
-    const store = await openStore({ storagePath: indexPath, dimensions: embedder.dimensions });
+    // Lazy one-time migration: move existing agent-memory records from
+    // index.nv into memory.nv on the first memory command run.
+    await migrateMemoryRecordsIfNeeded(indexPath, memoryPath, embedder.dimensions);
+    const store = await openStore({ storagePath: memoryPath, dimensions: embedder.dimensions });
     const [embedding] = await embedder.embed([value]);
     await store.upsert({
         id: randomUUID(),
@@ -59,9 +212,16 @@ export async function cmdMemorySearch(opts) {
     const { selectEmbedderFromEnv } = await import('../embedder/select.js');
     const { openStore, TENANT } = await import('../store/open.js');
     const buildRoot = resolveBuildRoot(opts.buildRoot, { cwd: opts.cwd ?? process.cwd() });
-    const indexPath = resolveIndexPath(buildRoot, opts.index);
+    // Resolve the memory-specific path (memory.nv), falling back to the
+    // legacy `index` flag for callers that pass it, then the default.
+    const memoryFlag = opts.memory ?? opts.index;
+    const memoryPath = resolveMemoryPath(buildRoot, memoryFlag);
+    const indexPath = resolveIndexPath(buildRoot, undefined);
     const embedder = await selectEmbedderFromEnv();
-    const store = await openStore({ storagePath: indexPath, dimensions: embedder.dimensions });
+    // Lazy one-time migration: move existing agent-memory records from
+    // index.nv into memory.nv on the first memory command run.
+    await migrateMemoryRecordsIfNeeded(indexPath, memoryPath, embedder.dimensions);
+    const store = await openStore({ storagePath: memoryPath, dimensions: embedder.dimensions });
     const [queryEmbedding] = await embedder.embed([query]);
     const result = await store.retrieveContext({
         embedding: queryEmbedding,

package/dist/commands/state-compile.d.ts

@@ -0,0 +1,108 @@
+/**
+ * `nuos-catalogue state compile` — STATE.md hybrid-document recompile (WU 113b / D132).
+ *
+ * Reads canonical state from the **live markdown registers** (not the workflow
+ * store, which is stale under Mode 1) and splices the generated sections into
+ * the sentinel-delimited regions of STATE.md, leaving all authored prose
+ * byte-for-byte identical.
+ *
+ * **Source-of-truth for each generated region (D129 / Mode 1):**
+ *   - Active WU:        `.nuos-catalogue/active-wu` marker file (WU 136 pointer)
+ *                       + title/status resolved from `work-units/_index.md`
+ *   - WUs in progress:  🟡 row count in `work-units/_index.md`
+ *   - WUs completed:    file count in `work-units/done/`
+ *   - Blocked WUs:      🔴 rows in `work-units/_index.md`
+ *   - Decisions:        `decisions/_index.md` active section
+ *   - Open questions:   `open-questions/_index.md` active section
+ *   - Risks:            `risks/_index.md` active section
+ *
+ * The workflow store (`workflows.json`) is accepted as a parameter for API
+ * compatibility (the CLI always opens it), but is NOT consulted for any of
+ * the above — it is frozen at migration time and would produce stale counts.
+ *
+ * **No LLM in this path.** The adapter builds an `LLMCompilationOutput`
+ * directly from disk state. `renderArticleMarkdown` is called per section,
+ * then `spliceGeneratedRegions` writes only inside the sentinel pairs.
+ *
+ * **First-cutover boundary.** If a sentinel region is absent from the target
+ * STATE.md, this command reports the missing regions clearly and exits
+ * non-zero without guessing where to insert them. The one-time insertion of
+ * sentinels into the live file is a manual operator step (Stage B walkthrough).
+ *
+ * D132 / D129 boundary:
+ *   - Generated regions: live markdown registers are source of truth; disk is
+ *     rendered projection for these regions only.
+ *   - Authored regions:  disk remains the edit base (untouched by this command).
+ */
+import type { LLMCompilationOutput, SentinelConfig } from '@nusoft/nuwiki';
+import { checkArticleDrift } from '@nusoft/nuwiki';
+import type { WorkflowStore } from '../migrate/store.js';
+export declare const STATE_SENTINEL_CONFIG: SentinelConfig;
+export declare const STATE_REGION_KEYS: {
+    readonly METADATA: "metadata";
+    readonly WHAT_IS_NEXT: "what_is_next";
+    readonly OPEN_QUESTIONS: "open_questions";
+    readonly RECENT_DECISIONS: "recent_decisions";
+    readonly RISKS: "risks";
+    readonly HEALTH_CHECK: "health_check";
+};
+export type StateRegionKey = (typeof STATE_REGION_KEYS)[keyof typeof STATE_REGION_KEYS];
+export interface StateSourceAdapterInput {
+    store: WorkflowStore;
+    buildRoot: string;
+    now?: string;
+}
+export interface StateCompiledOutput {
+    /** The structured body — one section per generated region. */
+    compilationOutput: LLMCompilationOutput;
+    /** The generated region contents keyed by region key (ready for splice). */
+    regions: Record<StateRegionKey, string>;
+}
+/**
+ * Reads canonical state from the live markdown registers and the active-WU
+ * marker file, and produces the generated content for each STATE.md region.
+ *
+ * No LLM call is made. The adapter derives all content deterministically.
+ * The workflow store parameter is accepted for API compatibility but is not
+ * consulted — see module-level comment for the source-of-truth map.
+ */
+export declare function buildStateCompilationOutput(input: StateSourceAdapterInput): Promise<StateCompiledOutput>;
+export interface StateCompileResult {
+    output: string;
+    exitCode: number;
+    updatedRegions?: string[];
+    unchangedRegions?: string[];
+}
+export declare function cmdStateCompile(store: WorkflowStore, args: {
+    buildRoot: string;
+    stateMdPath?: string;
+    dryRun?: boolean;
+    now?: string;
+}): Promise<StateCompileResult>;
+/**
+ * Expose `checkArticleDrift` with STATE.md's sentinel config pre-applied.
+ * Used by the pre-commit hook (Stage B) and tests.
+ */
+export declare function checkStateMdDrift(fileContent: string, expectedRegions: Record<string, string>): ReturnType<typeof checkArticleDrift>;
+export interface StateDriftCheckResult {
+    output: string;
+    exitCode: number;
+    /** 'clean' | 'drifted' | 'skipped' — used by tests */
+    verdict: 'clean' | 'drifted' | 'skipped';
+    driftedRegions?: string[];
+}
+/**
+ * Check whether the generated regions of STATE.md match what the canonical
+ * state currently produces. Designed to be called by the pre-commit hook.
+ *
+ * Exit-code contract (fail-open):
+ *   - exit 0  when generated regions are clean
+ *   - exit 0  when STATE.md has no sentinel regions yet (pre-cutover)
+ *   - exit 0  when the check cannot run (STATE.md unreadable, store missing)
+ *   - exit 1  ONLY on confirmed generated-region drift
+ */
+export declare function cmdStateDriftCheck(store: WorkflowStore, args: {
+    buildRoot: string;
+    stateMdPath?: string;
+    now?: string;
+}): Promise<StateDriftCheckResult>;