@nusoft/nuos-build-catalogue 0.33.3 → 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/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>;

package/dist/commands/state-compile.js

@@ -0,0 +1,793 @@
+/**
+ * `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 { readFile, writeFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { renderArticleMarkdown, spliceGeneratedRegions, checkArticleDrift, } from '@nusoft/nuwiki';
+import { resolveIndexDir } from '../path-resolution.js';
+// ---------------------------------------------------------------------------
+// Sentinel configuration — the marker scheme for STATE.md generated regions.
+// HTML-comment markers, compatible with STATE.md's existing nuos:sentinel scheme.
+// The `{{key}}` placeholder is replaced by the region key; `{{marker}}` is
+// replaced by the expanded marker.
+// ---------------------------------------------------------------------------
+export const STATE_SENTINEL_CONFIG = {
+    markerPattern: 'nuos:generated:{{key}}',
+    openTemplate: '<!-- {{marker}}:start -->',
+    closeTemplate: '<!-- {{marker}}:end -->',
+};
+// ---------------------------------------------------------------------------
+// Region keys — one per generated section (per WU 113b section map).
+// ---------------------------------------------------------------------------
+export const STATE_REGION_KEYS = {
+    METADATA: 'metadata',
+    WHAT_IS_NEXT: 'what_is_next',
+    OPEN_QUESTIONS: 'open_questions',
+    RECENT_DECISIONS: 'recent_decisions',
+    RISKS: 'risks',
+    HEALTH_CHECK: 'health_check',
+};
+/**
+ * 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 async function buildStateCompilationOutput(input) {
+    const { buildRoot } = input;
+    const now = input.now ?? new Date().toISOString();
+    const today = now.slice(0, 10);
+    // 1. Active WU — from the .nuos-catalogue/active-wu marker file (WU 136).
+    //    Title + status resolved from work-units/_index.md (live source).
+    const activeWu = await readActiveWuFromMarker(buildRoot);
+    // 2. Blocked WUs — from 🔴 rows in work-units/_index.md.
+    const blockedWorkflows = await readBlockedWorkflowsFromIndex(buildRoot);
+    // 3. Register indexes (all parsed from live disk files).
+    const unresolvedQuestions = await readUnresolvedQuestions(buildRoot);
+    const recentDecisions = await readRecentDecisions(buildRoot);
+    const activeRisks = await readActiveRisks(buildRoot);
+    const healthStats = await readHealthStatsFromDisk(buildRoot);
+    // 4. Build each section's text content.
+    const metadataText = renderMetadataSection(activeWu, today, healthStats);
+    const whatIsNextText = renderWhatIsNextSection(activeWu, blockedWorkflows);
+    const openQuestionsText = renderOpenQuestionsSection(unresolvedQuestions);
+    const recentDecisionsText = renderRecentDecisionsSection(recentDecisions);
+    const risksText = renderRisksSection(activeRisks);
+    const healthCheckText = renderHealthCheckSection(healthStats);
+    // 5. Assemble LLMCompilationOutput (one section per region, positionally ordered)
+    const sections = [
+        { key: STATE_REGION_KEYS.METADATA, heading: 'Metadata', text: metadataText, citationIds: [], position: 1 },
+        { key: STATE_REGION_KEYS.WHAT_IS_NEXT, heading: 'What is next', text: whatIsNextText, citationIds: [], position: 2 },
+        { key: STATE_REGION_KEYS.OPEN_QUESTIONS, heading: 'Open questions blocking active work', text: openQuestionsText, citationIds: [], position: 3 },
+        { key: STATE_REGION_KEYS.RECENT_DECISIONS, heading: 'Recent decisions', text: recentDecisionsText, citationIds: [], position: 4 },
+        { key: STATE_REGION_KEYS.RISKS, heading: 'Risks currently being watched', text: risksText, citationIds: [], position: 5 },
+        { key: STATE_REGION_KEYS.HEALTH_CHECK, heading: 'Health check', text: healthCheckText, citationIds: [], position: 6 },
+    ];
+    const compilationOutput = {
+        summary: `STATE.md compiled ${today} from live markdown registers. Active: ${activeWu?.handle ?? 'none'}.`,
+        sections,
+        citations: [],
+        outboundLinks: [],
+    };
+    // 5. Render each section to markdown (the splice expects the body text, no heading)
+    const regions = {};
+    for (const section of sections) {
+        const md = renderArticleMarkdown(compilationOutput, { sections: [section.key] });
+        // renderArticleMarkdown produces "## Heading\n\ntext\n" — we keep the full
+        // rendering including the heading so the sentinel region is self-contained.
+        regions[section.key] = md;
+    }
+    return { compilationOutput, regions };
+}
+export async function cmdStateCompile(store, args) {
+    const stateMdPath = args.stateMdPath ?? path.join(args.buildRoot, 'STATE.md');
+    // Read the current on-disk STATE.md — this is the edit base for authored prose.
+    let existingFile;
+    try {
+        existingFile = await readFile(stateMdPath, 'utf8');
+    }
+    catch (err) {
+        return {
+            output: `state compile: cannot read STATE.md at ${stateMdPath}\n  ${err instanceof Error ? err.message : String(err)}`,
+            exitCode: 1,
+        };
+    }
+    // Build the compiled output from canonical state.
+    let compiled;
+    try {
+        compiled = await buildStateCompilationOutput({
+            store,
+            buildRoot: args.buildRoot,
+            now: args.now,
+        });
+    }
+    catch (err) {
+        return {
+            output: `state compile: adapter error — ${err instanceof Error ? err.message : String(err)}`,
+            exitCode: 1,
+        };
+    }
+    // First-cutover guard: check that every region's sentinel pair is present.
+    // If any are missing, report them clearly and exit without modifying anything.
+    const missingRegions = [];
+    for (const key of Object.keys(compiled.regions)) {
+        const open = STATE_SENTINEL_CONFIG.openTemplate.replace('{{marker}}', STATE_SENTINEL_CONFIG.markerPattern.replace('{{key}}', key));
+        if (!existingFile.includes(open)) {
+            missingRegions.push(key);
+        }
+    }
+    if (missingRegions.length > 0) {
+        const lines = [
+            'state compile: the following sentinel regions are absent from STATE.md:',
+            '',
+        ];
+        for (const key of missingRegions) {
+            const marker = STATE_SENTINEL_CONFIG.markerPattern.replace('{{key}}', key);
+            lines.push(`  missing: <!-- ${marker}:start --> / <!-- ${marker}:end -->`);
+        }
+        lines.push('');
+        lines.push('This is expected on first cutover. The sentinel pairs must be inserted');
+        lines.push('manually into STATE.md by the operator (Stage B walkthrough) before');
+        lines.push('`state compile` can manage those regions.');
+        lines.push('');
+        lines.push('For each missing region, add a sentinel pair at the appropriate location:');
+        lines.push('  <!-- nuos:generated:<key>:start -->');
+        lines.push('  (generated content will appear here)');
+        lines.push('  <!-- nuos:generated:<key>:end -->');
+        return {
+            output: lines.join('\n'),
+            exitCode: 1,
+        };
+    }
+    // Splice the generated regions into the existing file.
+    let spliceResult;
+    try {
+        spliceResult = spliceGeneratedRegions({
+            existingFile,
+            regions: compiled.regions,
+            sentinelConfig: STATE_SENTINEL_CONFIG,
+        });
+    }
+    catch (err) {
+        return {
+            output: `state compile: splice error — ${err instanceof Error ? err.message : String(err)}`,
+            exitCode: 1,
+        };
+    }
+    if (args.dryRun) {
+        const lines = [
+            '',
+            '── state compile (dry run) ──────────────────────────────────────────',
+            `  target: ${stateMdPath}`,
+            `  updated regions: ${spliceResult.updatedRegions.length > 0 ? spliceResult.updatedRegions.join(', ') : '(none — already current)'}`,
+            `  unchanged regions: ${spliceResult.unchangedRegions.join(', ')}`,
+            '  (dry run — STATE.md was not written)',
+            '─────────────────────────────────────────────────────────────────────',
+            '',
+        ];
+        return {
+            output: lines.join('\n'),
+            exitCode: 0,
+            updatedRegions: spliceResult.updatedRegions,
+            unchangedRegions: spliceResult.unchangedRegions,
+        };
+    }
+    // Write the spliced content back to disk.
+    try {
+        await writeFile(stateMdPath, spliceResult.merged, 'utf8');
+    }
+    catch (err) {
+        return {
+            output: `state compile: cannot write STATE.md at ${stateMdPath}\n  ${err instanceof Error ? err.message : String(err)}`,
+            exitCode: 1,
+        };
+    }
+    const lines = [
+        '',
+        '── state compile ────────────────────────────────────────────────────',
+        `  target: ${stateMdPath}`,
+        `  updated regions: ${spliceResult.updatedRegions.length > 0 ? spliceResult.updatedRegions.join(', ') : '(none — already current)'}`,
+        `  unchanged regions: ${spliceResult.unchangedRegions.join(', ')}`,
+        '─────────────────────────────────────────────────────────────────────',
+        '',
+    ];
+    return {
+        output: lines.join('\n'),
+        exitCode: 0,
+        updatedRegions: spliceResult.updatedRegions,
+        unchangedRegions: spliceResult.unchangedRegions,
+    };
+}
+/**
+ * Expose `checkArticleDrift` with STATE.md's sentinel config pre-applied.
+ * Used by the pre-commit hook (Stage B) and tests.
+ */
+export function checkStateMdDrift(fileContent, expectedRegions) {
+    return checkArticleDrift({
+        file: fileContent,
+        sentinelConfig: STATE_SENTINEL_CONFIG,
+        expectedRegions,
+    });
+}
+/**
+ * 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 async function cmdStateDriftCheck(store, args) {
+    const stateMdPath = args.stateMdPath ?? path.join(args.buildRoot, 'STATE.md');
+    // Read the current on-disk STATE.md — if unreadable, fail open.
+    let existingFile;
+    try {
+        existingFile = await readFile(stateMdPath, 'utf8');
+    }
+    catch {
+        return {
+            output: `state drift-check: STATE.md unreadable at ${stateMdPath} — skipping (fail open)`,
+            exitCode: 0,
+            verdict: 'skipped',
+        };
+    }
+    // Pre-cutover guard: if none of the sentinel open-markers are present,
+    // the file has no sentinel regions yet — skip gracefully (fail open).
+    const hasAnySentinel = Object.values(STATE_REGION_KEYS).some((key) => {
+        const open = STATE_SENTINEL_CONFIG.openTemplate.replace('{{marker}}', STATE_SENTINEL_CONFIG.markerPattern.replace('{{key}}', key));
+        return existingFile.includes(open);
+    });
+    if (!hasAnySentinel) {
+        return {
+            output: 'state drift-check: no sentinel regions found in STATE.md — skipping (pre-cutover)',
+            exitCode: 0,
+            verdict: 'skipped',
+        };
+    }
+    // Build expected regions from canonical state.
+    let compiled;
+    try {
+        compiled = await buildStateCompilationOutput({
+            store,
+            buildRoot: args.buildRoot,
+            now: args.now,
+        });
+    }
+    catch {
+        return {
+            output: `state drift-check: adapter error — skipping (fail open)`,
+            exitCode: 0,
+            verdict: 'skipped',
+        };
+    }
+    // Run the drift check.
+    let driftReport;
+    try {
+        driftReport = checkStateMdDrift(existingFile, compiled.regions);
+    }
+    catch {
+        return {
+            output: `state drift-check: drift-check error — skipping (fail open)`,
+            exitCode: 0,
+            verdict: 'skipped',
+        };
+    }
+    if (driftReport.clean) {
+        return {
+            output: 'state drift-check: generated regions are current — clean',
+            exitCode: 0,
+            verdict: 'clean',
+        };
+    }
+    // Confirmed generated-region drift — exit non-zero.
+    const driftedRegions = driftReport.regions
+        .filter((r) => r.status !== 'clean')
+        .map((r) => r.key);
+    const lines = [
+        '✖ state drift-check: generated regions in STATE.md have drifted from canonical state.',
+        '',
+        `  Drifted region(s): ${driftedRegions.join(', ')}`,
+        '',
+        '  These regions are compiled deterministically from the workflow store and',
+        '  register indexes. Hand-editing them will be overwritten on next recompile.',
+        '',
+        '  To fix: recompile the generated regions and re-stage STATE.md:',
+        '    nuos-catalogue state compile',
+        '    git add docs/build/STATE.md',
+        '',
+        '  Then re-commit.',
+    ];
+    return {
+        output: lines.join('\n'),
+        exitCode: 1,
+        verdict: 'drifted',
+        driftedRegions,
+    };
+}
+/**
+ * Read the active WU from the `.nuos-catalogue/active-wu` marker file (WU 136).
+ * The handle stored there (e.g. `wu-113b`) is used to locate the matching row
+ * in `work-units/_index.md` to resolve the title and status.
+ *
+ * Degrades gracefully when:
+ *   - the marker file is absent or empty  → returns null (no active WU declared)
+ *   - the index row is not found          → returns the handle with unknown title/status
+ *   - the index file is unreadable        → returns the handle with unknown title/status
+ */
+async function readActiveWuFromMarker(buildRoot) {
+    const catalogueDir = resolveIndexDir(buildRoot);
+    const markerPath = path.join(catalogueDir, 'active-wu');
+    let handle;
+    try {
+        const raw = await readFile(markerPath, 'utf8');
+        handle = raw.trim();
+    }
+    catch {
+        return null; // marker absent — no active WU declared
+    }
+    if (!handle)
+        return null;
+    // The handle is e.g. "wu-113b". Strip the "wu-" prefix to get the ID as it
+    // appears in the _index.md ID column (e.g. "113b").
+    const idInIndex = handle.replace(/^wu-/i, '');
+    const slug = idInIndex;
+    const indexContent = await readIndexFile(path.join(buildRoot, 'work-units', '_index.md'));
+    if (!indexContent) {
+        return { handle, title: '(title unknown — index unreadable)', status: 'in_progress', slug };
+    }
+    // Parse the matching row. Row shape: `| 113b | [Title](file.md) | 🟡 in_progress — ... | ... |`
+    for (const line of indexContent.split('\n')) {
+        if (!/^\s*\|/.test(line))
+            continue;
+        const cells = line.split('|').map((c) => c.trim());
+        // cells[1] = ID cell, cells[2] = title cell, cells[3] = status cell
+        if (cells.length < 4)
+            continue;
+        const idCell = cells[1];
+        if (idCell !== idInIndex)
+            continue;
+        const titleCell = cells[2] ?? '';
+        // Strip markdown link syntax if present: [Title](file.md) → Title
+        const titleMatch = titleCell.match(/^\[([^\]]+)\]/) ?? titleCell.match(/^(.+)$/);
+        const title = titleMatch ? titleMatch[1].trim() : titleCell.trim();
+        const statusCell = cells[3] ?? '';
+        // Extract the status keyword (first word after the emoji, up to ' — ' or end)
+        const statusMatch = statusCell.match(/(?:🟡|🔴|🟢|🔵|🟣|✅|⚫)\s+(\S+)/);
+        const status = statusMatch ? statusMatch[1] : statusCell.split('—')[0].trim() || 'in_progress';
+        return { handle, title, status, slug };
+    }
+    // Handle declared but no matching row found in index
+    return { handle, title: '(title not found in work-units/_index.md)', status: 'in_progress', slug };
+}
+/**
+ * Read blocked WUs from 🔴 rows in `work-units/_index.md`.
+ * The workflow store is stale and must not be consulted for this.
+ */
+async function readBlockedWorkflowsFromIndex(buildRoot) {
+    const indexContent = await readIndexFile(path.join(buildRoot, 'work-units', '_index.md'));
+    if (!indexContent)
+        return [];
+    const blocked = [];
+    for (const line of indexContent.split('\n')) {
+        if (!/^\s*\|/.test(line))
+            continue;
+        if (!line.includes('🔴'))
+            continue;
+        const cells = line.split('|').map((c) => c.trim());
+        if (cells.length < 3)
+            continue;
+        const idCell = cells[1];
+        if (!idCell || /^[-\s]*$/.test(idCell) || idCell === 'ID')
+            continue;
+        const titleCell = cells[2] ?? '';
+        const titleMatch = titleCell.match(/^\[([^\]]+)\]/) ?? titleCell.match(/^(.+)$/);
+        const title = titleMatch ? titleMatch[1].trim() : titleCell.trim();
+        const handle = `wu-${idCell}`;
+        blocked.push({ handle, title });
+    }
+    return blocked;
+}
+async function readRecentDecisions(buildRoot) {
+    const indexContent = await readIndexFile(path.join(buildRoot, 'decisions', '_index.md'));
+    if (!indexContent)
+        return [];
+    return parseDecisionsIndex(indexContent);
+}
+async function readUnresolvedQuestions(buildRoot) {
+    const indexContent = await readIndexFile(path.join(buildRoot, 'open-questions', '_index.md'));
+    if (!indexContent)
+        return [];
+    return parseQuestionsIndex(indexContent);
+}
+async function readActiveRisks(buildRoot) {
+    const indexContent = await readIndexFile(path.join(buildRoot, 'risks', '_index.md'));
+    if (!indexContent)
+        return [];
+    return parseRisksIndex(indexContent);
+}
+/**
+ * Derive health stats entirely from live disk sources:
+ *   - in_progress / blocked counts: 🟡 / 🔴 rows in work-units/_index.md
+ *   - completed count: files in work-units/done/
+ *   - decisions count: active rows in decisions/_index.md
+ *   - open questions: active rows in open-questions/_index.md
+ *   - active risks: active rows in risks/_index.md
+ *
+ * The workflow store is NOT consulted (it is stale under Mode 1 — D129).
+ */
+async function readHealthStatsFromDisk(buildRoot) {
+    const wuIndex = await readIndexFile(path.join(buildRoot, 'work-units', '_index.md'));
+    let inProgressWus = 0;
+    let blockedWus = 0;
+    let maxInProgressWuNum = 0;
+    if (wuIndex) {
+        for (const line of wuIndex.split('\n')) {
+            if (!/^\s*\|/.test(line))
+                continue;
+            const cells = line.split('|').map((c) => c.trim());
+            if (cells.length < 4)
+                continue;
+            const idCell = cells[1];
+            if (!idCell || /^[-\s]*$/.test(idCell) || idCell === 'ID')
+                continue;
+            const statusCell = cells[3] ?? '';
+            if (statusCell.includes('🟡')) {
+                inProgressWus++;
+                // Extract the numeric part of the ID for phase derivation
+                const numMatch = idCell.match(/^(\d+)/);
+                if (numMatch) {
+                    const n = parseInt(numMatch[1], 10);
+                    if (n > maxInProgressWuNum)
+                        maxInProgressWuNum = n;
+                }
+            }
+            if (statusCell.includes('🔴'))
+                blockedWus++;
+        }
+    }
+    // Completed count: files in work-units/done/
+    let doneWus = 0;
+    try {
+        const doneEntries = await readdir(path.join(buildRoot, 'work-units', 'done'));
+        doneWus = doneEntries.filter((f) => f.endsWith('.md') && !f.startsWith('_')).length;
+    }
+    catch {
+        // done/ may not exist yet
+    }
+    // Decisions: active rows in decisions/_index.md
+    const decisionsIndex = await readIndexFile(path.join(buildRoot, 'decisions', '_index.md'));
+    let totalDecisions = 0;
+    if (decisionsIndex) {
+        const activeSection = decisionsIndex.split(/^## (?:Superseded|Withdrawn) decisions/im)[0];
+        for (const line of activeSection.split('\n')) {
+            if (!/^\s*\|/.test(line))
+                continue;
+            const cells = line.split('|').map((c) => c.trim());
+            if (cells.length < 3)
+                continue;
+            const idCell = cells[1];
+            if (!idCell || /^[-\s]*$/.test(idCell) || idCell === 'ID' || idCell === '---')
+                continue;
+            if (/^D\d+/i.test(idCell.replace(/^\[/, '')))
+                totalDecisions++;
+        }
+    }
+    // Open questions: active section
+    const questionsIndex = await readIndexFile(path.join(buildRoot, 'open-questions', '_index.md'));
+    let openQuestions = 0;
+    if (questionsIndex) {
+        const activeSection = questionsIndex.split(/^## Resolved questions/im)[0];
+        for (const line of activeSection.split('\n')) {
+            if (!/^\s*\|/.test(line))
+                continue;
+            const cells = line.split('|').map((c) => c.trim());
+            if (cells.length < 3)
+                continue;
+            const idCell = cells[1];
+            if (!idCell || /^[-\s]*$/.test(idCell) || idCell === 'ID' || idCell === '---')
+                continue;
+            if (/^Q\d+/i.test(idCell.replace(/^\[/, '')))
+                openQuestions++;
+        }
+    }
+    // Active risks: active section
+    const risksIndex = await readIndexFile(path.join(buildRoot, 'risks', '_index.md'));
+    let activeRisks = 0;
+    if (risksIndex) {
+        const activeSection = risksIndex.split(/^## Resolved risks/im)[0];
+        for (const line of activeSection.split('\n')) {
+            if (!/^\s*\|/.test(line))
+                continue;
+            const cells = line.split('|').map((c) => c.trim());
+            if (cells.length < 3)
+                continue;
+            const idCell = cells[1];
+            if (!idCell || /^[-\s]*$/.test(idCell) || idCell === 'ID' || idCell === '---')
+                continue;
+            if (/^R\d+/i.test(idCell))
+                activeRisks++;
+        }
+    }
+    return { inProgressWus, doneWus, blockedWus, totalDecisions, openQuestions, activeRisks, maxInProgressWuNum };
+}
+// ---------------------------------------------------------------------------
+// Text renderers for each section
+// ---------------------------------------------------------------------------
+function renderMetadataSection(activeWu, today, stats) {
+    const phase = deriveCurrentPhase(stats.maxInProgressWuNum);
+    const lines = [
+        '| Field | Value |',
+        '| --- | --- |',
+        `| Last compiled | ${today} |`,
+        `| Current phase | ${phase} |`,
+        `| Active WU | ${activeWu ? `**${activeWu.handle}** — ${activeWu.title} (${activeWu.status ?? 'unknown'})` : '(no active WU declared — run `nuos-catalogue wu start <handle>`)'} |`,
+        `| WUs in progress | ${stats.inProgressWus} |`,
+    ];
+    return lines.join('\n');
+}
+/**
+ * Derive the current phase label from the highest in-progress WU number
+ * (read from the live `work-units/_index.md`, not the store).
+ */
+function deriveCurrentPhase(maxInProgressWuNum) {
+    if (maxInProgressWuNum === 0)
+        return 'No active phase detected';
+    if (maxInProgressWuNum >= 100)
+        return 'Continuous Track 1 — NuOS leads the build';
+    if (maxInProgressWuNum >= 80)
+        return 'Phase 5 — Consumer shell + productisation';
+    if (maxInProgressWuNum >= 60)
+        return 'Phase 4 — Trifecta integration test';
+    if (maxInProgressWuNum >= 40)
+        return 'Phase 3 — NuWiki + trifecta';
+    if (maxInProgressWuNum >= 20)
+        return 'Phase 2 — NuFlow';
+    return 'Phase 1 — NuVector';
+}
+function renderWhatIsNextSection(activeWu, blockedWorkflows) {
+    if (!activeWu) {
+        return [
+            'No active WU marker found. Declare the active WU with:',
+            '    nuos-catalogue wu start <handle>',
+            '',
+            'Then recompile STATE.md with `nuos-catalogue state compile`.',
+        ].join('\n');
+    }
+    const lines = [
+        `**Active WU: ${activeWu.handle}** — ${activeWu.title}`,
+        `Status: \`${activeWu.status ?? 'in_progress'}\``,
+    ];
+    if (blockedWorkflows.length > 0) {
+        lines.push('');
+        lines.push('**Blocked work units requiring attention:**');
+        for (const b of blockedWorkflows) {
+            lines.push(`- ${b.handle} — ${b.title}`);
+        }
+    }
+    lines.push('');
+    lines.push('Continue the active WU. Recompile STATE.md at end-of-session via `nuos-catalogue state compile`.');
+    return lines.join('\n');
+}
+function renderOpenQuestionsSection(questions) {
+    if (questions.length === 0) {
+        return 'No unresolved open questions. See `docs/build/open-questions/_index.md` for the full register.';
+    }
+    const lines = [];
+    for (const q of questions.slice(0, 10)) {
+        const blocks = q.blocks ? ` — blocks: ${q.blocks}` : '';
+        lines.push(`- **${q.id}** — ${q.title}${blocks}`);
+    }
+    if (questions.length > 10) {
+        lines.push(`- *(${questions.length - 10} more — see open-questions/_index.md)*`);
+    }
+    return lines.join('\n');
+}
+function renderRecentDecisionsSection(decisions) {
+    if (decisions.length === 0) {
+        return 'No decisions found. See `docs/build/decisions/_index.md` for the full register.';
+    }
+    const recent = decisions.slice(0, 8);
+    const lines = [];
+    for (const d of recent) {
+        lines.push(`- **${d.handle}** — ${d.title}${d.status ? ` *(${d.status})*` : ''}`);
+    }
+    if (decisions.length > 8) {
+        lines.push(`- *(${decisions.length - 8} more — see decisions/_index.md)*`);
+    }
+    return lines.join('\n');
+}
+function renderRisksSection(risks) {
+    if (risks.length === 0) {
+        return 'No active risks found. See `docs/build/risks/_index.md` for the full register.';
+    }
+    const lines = [];
+    for (const r of risks.slice(0, 5)) {
+        lines.push(`- **${r.id}** (${r.severity}) — ${r.title} *(${r.status})*`);
+    }
+    if (risks.length > 5) {
+        lines.push(`- *(${risks.length - 5} more — see risks/_index.md)*`);
+    }
+    return lines.join('\n');
+}
+function renderHealthCheckSection(stats) {
+    const lines = [
+        '| Check | Count |',
+        '| --- | --- |',
+        `| WUs in progress | ${stats.inProgressWus} |`,
+        `| WUs completed | ${stats.doneWus} (files in work-units/done/) |`,
+        `| Decisions recorded | ${stats.totalDecisions} (active section) |`,
+        `| Open questions | ${stats.openQuestions} |`,
+        `| Active risks | ${stats.activeRisks} |`,
+    ];
+    if (stats.blockedWus > 0) {
+        lines.push(`| Blocked WUs | ${stats.blockedWus} — attention needed |`);
+    }
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Index file parsers
+// ---------------------------------------------------------------------------
+async function readIndexFile(filePath) {
+    try {
+        const { readFile: rf } = await import('node:fs/promises');
+        return await rf(filePath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse the decisions _index.md table — active decisions only.
+ * Row shape: `| [D001](file.md) | Title | Date | Status |`
+ * or: `| D001 | Title | Date | Status |`
+ *
+ * The real decisions/_index.md has three terminal sections after the active
+ * table: `## Superseded decisions`, `## Withdrawn decisions`, and
+ * `## How to write a decision`. We split on the first non-active section
+ * (whichever of Superseded / Withdrawn appears first) so a high-numbered
+ * decision that is later superseded never leaks into the generated region.
+ */
+function parseDecisionsIndex(content) {
+    const decisions = [];
+    // Scope to the active-decisions section only.
+    // Split on the first of the two non-active `##` headers that follow it.
+    const activeSection = content.split(/^## (?:Superseded|Withdrawn) decisions/im)[0];
+    const lines = activeSection.split('\n');
+    for (const line of lines) {
+        if (!/^\s*\|/.test(line))
+            continue;
+        const cells = line.split('|').map((c) => c.trim());
+        // Expect: [empty, id-cell, title, date, status, empty]
+        if (cells.length < 5)
+            continue;
+        const idCell = cells[1];
+        if (!idCell || !/^D\d+/i.test(idCell.replace(/^\[/, '')))
+            continue;
+        // Extract the handle — strip link markup if present
+        const handleMatch = idCell.match(/\[?(D\d+)\]?/i);
+        if (!handleMatch)
+            continue;
+        const handle = handleMatch[1];
+        const title = cells[2] ?? '';
+        if (!title || title === 'Title' || title === '---')
+            continue;
+        const status = cells[4] ?? null;
+        if (status === 'Status' || status === '---')
+            continue;
+        decisions.push({
+            handle,
+            title,
+            status: status || null,
+            fileModifiedAt: cells[3] ?? '',
+        });
+    }
+    // Sort by handle number descending to get most recent first
+    return decisions.sort((a, b) => {
+        const na = parseInt(a.handle.slice(1), 10);
+        const nb = parseInt(b.handle.slice(1), 10);
+        return nb - na;
+    });
+}
+/**
+ * Parse the open-questions _index.md active table.
+ * Row shape: `| [Q003](file.md) | Title | Blocks | Raised |`
+ * or: `| Q003 | Title | Blocks | Raised |`
+ */
+function parseQuestionsIndex(content) {
+    const questions = [];
+    // Find the "Active questions" section — stop at "Resolved questions"
+    const activeSection = content.split(/^## Resolved questions/im)[0];
+    const lines = activeSection.split('\n');
+    for (const line of lines) {
+        if (!/^\s*\|/.test(line))
+            continue;
+        const cells = line.split('|').map((c) => c.trim());
+        if (cells.length < 4)
+            continue;
+        const idCell = cells[1];
+        if (!idCell || !/^Q\d+/i.test(idCell.replace(/^\[/, '')))
+            continue;
+        const idMatch = idCell.match(/\[?(Q\d+)\]?/i);
+        if (!idMatch)
+            continue;
+        const id = idMatch[1];
+        const title = cells[2] ?? '';
+        if (!title || title === 'Title' || title === '---')
+            continue;
+        const blocks = cells[3] ?? '';
+        if (blocks === 'Blocks' || blocks === '---')
+            continue;
+        questions.push({ id, title, blocks });
+    }
+    return questions;
+}
+/**
+ * Parse the risks _index.md active table.
+ * Row shape: `| R001 | Title | Severity | Likelihood | Status |`
+ */
+function parseRisksIndex(content) {
+    const risks = [];
+    // Find the "Active risks" section — stop at "Resolved risks"
+    const activeSection = content.split(/^## Resolved risks/im)[0];
+    const lines = activeSection.split('\n');
+    for (const line of lines) {
+        if (!/^\s*\|/.test(line))
+            continue;
+        const cells = line.split('|').map((c) => c.trim());
+        if (cells.length < 6)
+            continue;
+        const idCell = cells[1];
+        if (!idCell || !/^R\d+/i.test(idCell))
+            continue;
+        if (idCell === 'ID' || idCell === '---')
+            continue;
+        const id = idCell;
+        const title = cells[2] ?? '';
+        if (!title || title === 'Title' || title === '---')
+            continue;
+        const severity = cells[3] ?? '';
+        const likelihood = cells[4] ?? '';
+        const status = cells[5] ?? '';
+        if (status === 'Status' || status === '---')
+            continue;
+        risks.push({ id, title, severity, likelihood, status });
+    }
+    return risks;
+}

package/dist/embedder/ollama.d.ts

@@ -32,6 +32,13 @@
  * idle-timeout (the keep_alive: "1m" we sent) cleans up within a
  * minute.
  *
+ * **Bounded footprint while loaded.** Beyond unloading promptly, each call
+ * also pins `options.num_ctx` (see EMBED_NUM_CTX) so the model loads with an
+ * embedding-sized context window instead of inheriting the daemon's
+ * chat-sized OLLAMA_CONTEXT_LENGTH. Without this the 639MB model loads at
+ * ~5.7GB resident; with it, ~1.1GB. This is what keeps a reindex from pushing
+ * a developer's machine into swap.
+ *
  * Sizing note — the new 0.6b default is ~600MB on disk and runs
  * comfortably on any modern laptop, including CPU-only. The 4b variant
  * (~2.5GB) and 8b variant (~4.7GB, benefits from ~16GB RAM + Metal)

package/dist/embedder/ollama.js

@@ -32,6 +32,13 @@
  * idle-timeout (the keep_alive: "1m" we sent) cleans up within a
  * minute.
  *
+ * **Bounded footprint while loaded.** Beyond unloading promptly, each call
+ * also pins `options.num_ctx` (see EMBED_NUM_CTX) so the model loads with an
+ * embedding-sized context window instead of inheriting the daemon's
+ * chat-sized OLLAMA_CONTEXT_LENGTH. Without this the 639MB model loads at
+ * ~5.7GB resident; with it, ~1.1GB. This is what keeps a reindex from pushing
+ * a developer's machine into swap.
+ *
  * Sizing note — the new 0.6b default is ~600MB on disk and runs
  * comfortably on any modern laptop, including CPU-only. The 4b variant
  * (~2.5GB) and 8b variant (~4.7GB, benefits from ~16GB RAM + Metal)
@@ -47,6 +54,16 @@ const KNOWN_DIMENSIONS = {
     'qwen3-embedding:4b': 2560,
     'qwen3-embedding:0.6b': 1024,
 };
+// Context window for embedding loads. The Ollama daemon's global
+// OLLAMA_CONTEXT_LENGTH — set high for chat models (commonly 32K–64K) — is
+// inherited by every model that doesn't override it. Inherited unchanged, it
+// inflates the 639MB qwen3-embedding:0.6b model to ~5.7GB resident, which is
+// enough to push a 16–18GB developer machine into swap during a reindex.
+// Embedding inputs are capped at ~600 tokens (MAX_CHUNK_CHARS in
+// indexer/chunk.ts), so a 2048-token window leaves ~3x headroom and never
+// truncates a chunk. Measured 2026-06-01 (qwen3-embedding:0.6b, Apple Silicon):
+// inherited 32K ctx → 5.7GB resident; num_ctx 2048 → 1.1GB resident.
+const EMBED_NUM_CTX = 2048;
 export class OllamaEmbedder {
     dimensions;
     modelId;
@@ -68,7 +85,13 @@ export class OllamaEmbedder {
             const probe = await fetch(`${host}/api/embed`, {
                 method: 'POST',
                 headers: { 'content-type': 'application/json' },
-                body: JSON.stringify({ model: modelId, input: 'probe' }),
+                body: JSON.stringify({
+                    model: modelId,
+                    input: 'probe',
+                    // Pin the context window here too — the probe is what first loads the
+                    // model, so without it the probe alone would pull in the full ~5.7GB.
+                    options: { num_ctx: EMBED_NUM_CTX },
+                }),
             });
             if (!probe.ok) {
                 const body = await probe.text().catch(() => '<unreadable>');
@@ -121,6 +144,9 @@ export class OllamaEmbedder {
                 // Keep the model warm only for the duration of one operation.
                 // dispose() at the end of the run sends keep_alive: 0 to unload.
                 keep_alive: '1m',
+                // Cap the context window so the model loads at ~1.1GB rather than
+                // inheriting the daemon's chat-sized window and ballooning to ~5.7GB.
+                options: { num_ctx: EMBED_NUM_CTX },
             }),
         });
         if (!res.ok) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nusoft/nuos-build-catalogue",
-  "version": "0.33.3",
+  "version": "0.35.1",
   "description": "NuOS build-catalogue tooling: semantic search (WU 110) + migration runner that lifts markdown artefacts into JSON-backed workflow records (WU 111, Phase G).",
   "type": "module",
   "bin": {
@@ -19,15 +19,16 @@
     "build": "rm -rf dist && tsc && chmod +x dist/cli.js",
     "prepublishOnly": "npm run build",
     "verify-storage": "tsx scripts/verify-persistence.ts",
-    "test": "tsx --test tests/chunk.test.ts tests/metadata.test.ts tests/crawl.test.ts tests/migrate.test.ts tests/commands-read.test.ts tests/regenerate.test.ts tests/commands-write.test.ts tests/ac-parse.test.ts tests/create.test.ts tests/init.test.ts tests/wu-111-soak-findings.test.ts tests/plan.test.ts tests/mode.test.ts tests/render.test.ts tests/swarm.test.ts tests/setup-progress-bar.test.ts tests/setup-ollama-pull.test.ts tests/setup-run-llm-setup.test.ts tests/wu-active.test.ts tests/install-claude-hooks.test.ts tests/protocols-in-sync.test.ts tests/end-of-session.test.ts tests/hooks-in-sync.test.ts tests/memory-store-separation.test.ts",
+    "test": "tsx --test tests/chunk.test.ts tests/metadata.test.ts tests/crawl.test.ts tests/migrate.test.ts tests/commands-read.test.ts tests/regenerate.test.ts tests/commands-write.test.ts tests/ac-parse.test.ts tests/create.test.ts tests/init.test.ts tests/wu-111-soak-findings.test.ts tests/plan.test.ts tests/mode.test.ts tests/render.test.ts tests/swarm.test.ts tests/setup-progress-bar.test.ts tests/setup-ollama-pull.test.ts tests/setup-run-llm-setup.test.ts tests/wu-active.test.ts tests/install-claude-hooks.test.ts tests/protocols-in-sync.test.ts tests/end-of-session.test.ts tests/hooks-in-sync.test.ts tests/memory-store-separation.test.ts tests/state-compile.test.ts tests/state-drift-check.test.ts tests/hook-isolation.test.ts",
     "typecheck": "tsc --noEmit",
     "index": "tsx src/cli.ts index",
     "search": "tsx src/cli.ts search"
   },
   "dependencies": {
-    "@nusoft/nuvector": "^0.1.5",
     "@nusoft/nuflow": "^0.4.1",
-    "@nusoft/nuflow-pack-nuos-build-catalogue": "^0.1.0"
+    "@nusoft/nuflow-pack-nuos-build-catalogue": "^0.3.0",
+    "@nusoft/nuvector": "^0.1.5",
+    "@nusoft/nuwiki": "^0.3.0"
   },
   "devDependencies": {
     "@nusoft/nuflow": "file:../nuflow",

package/scripts/hooks/pre-commit

@@ -177,6 +177,49 @@ if [[ -n "$locked_decisions" ]]; then
   EXIT_CODE=1
 fi
 
+# ---------- Rule 3: STATE.md generated-region drift block (WU 113b Stage B) ---
+
+# Only run when docs/build/STATE.md is in the staged changes.
+# Guard on nuos-catalogue being present and supporting `state drift-check`.
+# Fail-open: if the binary is absent, old (doesn't know drift-check), or
+# errors for any infra reason, skip this check silently — a missing binary
+# must never block all commits.
+#
+# Old-binary detection: an old binary (< 0.35.0) exits non-zero with
+# "unknown state subcommand: drift-check" on stderr. We distinguish this
+# from a genuine drift finding by checking whether the output contains the
+# drift-specific marker phrase. If the output does NOT contain "generated regions"
+# (the phrase only the new drift-check command emits), we skip.
+staged_state_md=$(git diff --cached --name-only | grep -F 'docs/build/STATE.md' || true)
+
+if [[ -n "$staged_state_md" ]]; then
+  dim "[nuos:pre-commit] STATE.md generated-region drift check (WU 113b)"
+
+  if ! command -v nuos-catalogue > /dev/null 2>&1; then
+    dim "[nuos:pre-commit] nuos-catalogue not found — skipping STATE.md drift check"
+  else
+    # Run drift-check; capture output + exit code.
+    drift_output=$(nuos-catalogue state drift-check 2>&1) || drift_exit=$?
+    drift_exit=${drift_exit:-0}
+
+    if [[ $drift_exit -ne 0 ]]; then
+      # Non-zero exit — check whether this is a genuine drift finding or an
+      # infra/version problem (old binary, missing store, etc.).
+      if echo "$drift_output" | grep -qF 'generated regions'; then
+        # Confirmed generated-region drift — block the commit.
+        red "✖ STATE.md generated-region drift — BLOCKED (WU 113b enforcement):"
+        echo "$drift_output" | while IFS= read -r line; do echo "  $line"; done
+        log_event "state-drift-block" "generated-region drift detected"
+        EXIT_CODE=1
+      else
+        # Not a drift finding (unknown subcommand from old binary, infra error, etc.)
+        # — skip silently (fail open).
+        dim "[nuos:pre-commit] STATE.md drift check returned non-zero (not a drift finding) — skipping"
+      fi
+    fi
+  fi
+fi
+
 # ---------- Result ------------------------------------------------------
 
 if [[ $EXIT_CODE -eq 0 ]]; then

package/templates/hooks/pre-commit

@@ -177,6 +177,49 @@ if [[ -n "$locked_decisions" ]]; then
   EXIT_CODE=1
 fi
 
+# ---------- Rule 3: STATE.md generated-region drift block (WU 113b Stage B) ---
+
+# Only run when docs/build/STATE.md is in the staged changes.
+# Guard on nuos-catalogue being present and supporting `state drift-check`.
+# Fail-open: if the binary is absent, old (doesn't know drift-check), or
+# errors for any infra reason, skip this check silently — a missing binary
+# must never block all commits.
+#
+# Old-binary detection: an old binary (< 0.35.0) exits non-zero with
+# "unknown state subcommand: drift-check" on stderr. We distinguish this
+# from a genuine drift finding by checking whether the output contains the
+# drift-specific marker phrase. If the output does NOT contain "generated regions"
+# (the phrase only the new drift-check command emits), we skip.
+staged_state_md=$(git diff --cached --name-only | grep -F 'docs/build/STATE.md' || true)
+
+if [[ -n "$staged_state_md" ]]; then
+  dim "[nuos:pre-commit] STATE.md generated-region drift check (WU 113b)"
+
+  if ! command -v nuos-catalogue > /dev/null 2>&1; then
+    dim "[nuos:pre-commit] nuos-catalogue not found — skipping STATE.md drift check"
+  else
+    # Run drift-check; capture output + exit code.
+    drift_output=$(nuos-catalogue state drift-check 2>&1) || drift_exit=$?
+    drift_exit=${drift_exit:-0}
+
+    if [[ $drift_exit -ne 0 ]]; then
+      # Non-zero exit — check whether this is a genuine drift finding or an
+      # infra/version problem (old binary, missing store, etc.).
+      if echo "$drift_output" | grep -qF 'generated regions'; then
+        # Confirmed generated-region drift — block the commit.
+        red "✖ STATE.md generated-region drift — BLOCKED (WU 113b enforcement):"
+        echo "$drift_output" | while IFS= read -r line; do echo "  $line"; done
+        log_event "state-drift-block" "generated-region drift detected"
+        EXIT_CODE=1
+      else
+        # Not a drift finding (unknown subcommand from old binary, infra error, etc.)
+        # — skip silently (fail open).
+        dim "[nuos:pre-commit] STATE.md drift check returned non-zero (not a drift finding) — skipping"
+      fi
+    fi
+  fi
+fi
+
 # ---------- Result ------------------------------------------------------
 
 if [[ $EXIT_CODE -eq 0 ]]; then