@nusoft/nuos-build-catalogue 0.33.3 → 0.36.0

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/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>;