@nusoft/nuos-build-catalogue 0.12.0 → 0.14.1

package/dist/commands/write.js

@@ -86,16 +86,25 @@ function inferWorkflowStatus(record) {
 }
 // ---------------------------------------------------------------------------
 // wu tick <handle> --index=N --evidence="..."
+//
+// --index is **1-based** at the CLI boundary (so --index=1 ticks the first
+// AC). Internally the pack workflow + ac-parse use 0-based indexing; the
+// conversion happens here so the user-facing surface matches the
+// human-readable summary text the mis-adapter writes into the markdown
+// changelog ("Acceptance criterion 3 ticked: ...").
 // ---------------------------------------------------------------------------
 export async function cmdWuTick(store, runtime, args) {
     if (!args.handle) {
         return {
-            output: 'Usage: nuos-catalogue wu tick <handle> --index=N --evidence="..."',
+            output: 'Usage: nuos-catalogue wu tick <handle> --index=N --evidence="..."  (--index is 1-based)',
             exitCode: 2,
         };
     }
-    if (typeof args.index !== 'number' || !Number.isInteger(args.index) || args.index < 0) {
-        return { output: '--index=<non-negative integer> is required', exitCode: 2 };
+    if (typeof args.index !== 'number' || !Number.isInteger(args.index) || args.index < 1) {
+        return {
+            output: '--index=<positive integer> is required (1-based: --index=1 ticks the first AC)',
+            exitCode: 2,
+        };
     }
     if (!args.evidence || args.evidence.trim().length === 0) {
         return { output: '--evidence="..." is required (non-empty)', exitCode: 2 };
@@ -104,17 +113,19 @@ export async function cmdWuTick(store, runtime, args) {
     if (!store.has(handle)) {
         return { output: `no work_unit record for handle "${handle}"`, exitCode: 1 };
     }
+    // Convert 1-based CLI input to 0-based for the workflow + ac-parse layer.
+    const zeroBasedIndex = args.index - 1;
     const capture = {
         channel: 'typed_note',
         content: `tick AC #${args.index} on ${handle}`,
         subjects: [{ kind: 'work_unit', id: handle }],
         metadata: {
             targetHandle: handle,
-            criterionIndex: args.index,
+            criterionIndex: zeroBasedIndex,
             evidence: args.evidence,
         },
     };
-    return await driveLifecycle(runtime, 'work_unit.tick_acceptance_criterion', capture, handle, `index ${args.index}`);
+    return await driveLifecycle(runtime, 'work_unit.tick_acceptance_criterion', capture, handle, `AC ${args.index}`);
 }
 // ---------------------------------------------------------------------------
 // decision supersede <target> --by=<superseding> [--reason="..."]

package/dist/path-resolution.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Default path resolution for the CLI.
+ *
+ * Defaults walk up from `process.cwd()` to find the nearest directory
+ * containing `docs/build/`, the same way `git` finds its repo root.
+ * That makes the CLI work consistently regardless of where it was
+ * installed from (sibling checkout, npx cache, global install) and
+ * regardless of which subdirectory the operator invokes it from.
+ *
+ * Resolution order, for every path-shaped flag:
+ *   1. Explicit `--flag=<value>` (highest precedence)
+ *   2. Matching `NUOS_CATALOGUE_*` env var
+ *   3. Walk-up discovery from cwd
+ *   4. Throw with a clear hint, OR fall back to cwd, depending on the
+ *      flag's semantics (build-root throws because there's no honest
+ *      default; storage dirs fall back to cwd because creating them
+ *      ad-hoc is reasonable when no project root is found).
+ */
+/**
+ * Walk up from `startDir` looking for a directory that contains a
+ * `docs/build/` subdirectory. Returns the absolute path to the
+ * containing directory, or null if no such directory is found before
+ * reaching the filesystem root.
+ *
+ * Exposed for testing; ordinary callers use `resolveBuildRoot` etc.
+ */
+export declare function findProjectRoot(startDir: string): string | null;
+export interface ResolutionContext {
+    /** Override for `process.cwd()` — used by tests to anchor walk-up. */
+    cwd?: string;
+    /** Override for `process.env` — used by tests to control env vars. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Resolve the build catalogue root. Throws with a clear hint when no
+ * value is available — the build root is load-bearing for every write
+ * command, so a silent fallback would mask real errors.
+ */
+export declare function resolveBuildRoot(flag: string | boolean | undefined, ctx?: ResolutionContext): string;
+/**
+ * Resolve the wider documentation root for semantic-search indexing.
+ * Falls back to `<project-root>/docs` when no flag or env var is set,
+ * because semantic-search has always indexed the wider docs/ surface,
+ * not just docs/build/.
+ */
+export declare function resolveCatalogueRoot(flag: string | boolean | undefined, ctx?: ResolutionContext): string;
+/**
+ * Resolve the `.nuos-catalogue/` storage directory. Always co-located
+ * with the project root (the directory containing `docs/build/`).
+ * `NUOS_CATALOGUE_INDEX_DIR` env var wins when set.
+ */
+export declare function resolveIndexDir(buildRoot: string, ctx?: ResolutionContext): string;
+export declare function resolveWorkflowsPath(buildRoot: string, flag: string | boolean | undefined, ctx?: ResolutionContext): string;
+export declare function resolveIndexPath(buildRoot: string, flag: string | boolean | undefined, ctx?: ResolutionContext): string;
+export declare function resolveHashPath(buildRoot: string, flag: string | boolean | undefined, ctx?: ResolutionContext): string;
+/**
+ * Soft warning surfaced after a `migrate` or `regenerate` run: if the
+ * project has a `.gitignore` at its root and that `.gitignore` does
+ * NOT contain a `.nuos-catalogue/` entry, the workflow store appears
+ * as untracked. Returns a multi-line `note:` string when a warning
+ * should be printed, or null when silent.
+ *
+ * Silent when:
+ *   - the project has no `.gitignore` (it might not be a git repo)
+ *   - the gitignore already excludes `.nuos-catalogue/`
+ *   - the gitignore can't be read for any reason (be quiet, not noisy)
+ */
+export declare function gitignoreCatalogueNote(buildRoot: string, ctx?: ResolutionContext): string | null;

package/dist/path-resolution.js

@@ -0,0 +1,147 @@
+/**
+ * Default path resolution for the CLI.
+ *
+ * Defaults walk up from `process.cwd()` to find the nearest directory
+ * containing `docs/build/`, the same way `git` finds its repo root.
+ * That makes the CLI work consistently regardless of where it was
+ * installed from (sibling checkout, npx cache, global install) and
+ * regardless of which subdirectory the operator invokes it from.
+ *
+ * Resolution order, for every path-shaped flag:
+ *   1. Explicit `--flag=<value>` (highest precedence)
+ *   2. Matching `NUOS_CATALOGUE_*` env var
+ *   3. Walk-up discovery from cwd
+ *   4. Throw with a clear hint, OR fall back to cwd, depending on the
+ *      flag's semantics (build-root throws because there's no honest
+ *      default; storage dirs fall back to cwd because creating them
+ *      ad-hoc is reasonable when no project root is found).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * Walk up from `startDir` looking for a directory that contains a
+ * `docs/build/` subdirectory. Returns the absolute path to the
+ * containing directory, or null if no such directory is found before
+ * reaching the filesystem root.
+ *
+ * Exposed for testing; ordinary callers use `resolveBuildRoot` etc.
+ */
+export function findProjectRoot(startDir) {
+    let dir = path.resolve(startDir);
+    while (true) {
+        if (existsSync(path.join(dir, 'docs', 'build')))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function ctxCwd(ctx) {
+    return ctx?.cwd ?? process.cwd();
+}
+function ctxEnv(ctx) {
+    return ctx?.env ?? process.env;
+}
+/**
+ * Resolve the build catalogue root. Throws with a clear hint when no
+ * value is available — the build root is load-bearing for every write
+ * command, so a silent fallback would mask real errors.
+ */
+export function resolveBuildRoot(flag, ctx) {
+    if (typeof flag === 'string' && flag.length > 0)
+        return path.resolve(flag);
+    const env = ctxEnv(ctx);
+    if (env.NUOS_CATALOGUE_BUILD_ROOT)
+        return path.resolve(env.NUOS_CATALOGUE_BUILD_ROOT);
+    const root = findProjectRoot(ctxCwd(ctx));
+    if (root)
+        return path.join(root, 'docs', 'build');
+    throw new Error('cannot locate the build catalogue (no docs/build/ directory found from cwd or any parent).\n' +
+        'Either:\n' +
+        '  - run from a project that has been bootstrapped via `nuos-catalogue init`,\n' +
+        '  - set NUOS_CATALOGUE_BUILD_ROOT in your shell profile,\n' +
+        '  - or pass --build-root=<dir> to this command.');
+}
+/**
+ * Resolve the wider documentation root for semantic-search indexing.
+ * Falls back to `<project-root>/docs` when no flag or env var is set,
+ * because semantic-search has always indexed the wider docs/ surface,
+ * not just docs/build/.
+ */
+export function resolveCatalogueRoot(flag, ctx) {
+    if (typeof flag === 'string' && flag.length > 0)
+        return path.resolve(flag);
+    const env = ctxEnv(ctx);
+    if (env.NUOS_CATALOGUE_ROOT)
+        return path.resolve(env.NUOS_CATALOGUE_ROOT);
+    const root = findProjectRoot(ctxCwd(ctx));
+    if (root)
+        return path.join(root, 'docs');
+    throw new Error('cannot locate the docs/ directory (no docs/build/ found from cwd or any parent).\n' +
+        'Either set NUOS_CATALOGUE_ROOT, or pass --catalogue=<dir>.');
+}
+/**
+ * Resolve the `.nuos-catalogue/` storage directory. Always co-located
+ * with the project root (the directory containing `docs/build/`).
+ * `NUOS_CATALOGUE_INDEX_DIR` env var wins when set.
+ */
+export function resolveIndexDir(buildRoot, ctx) {
+    const env = ctxEnv(ctx);
+    if (env.NUOS_CATALOGUE_INDEX_DIR)
+        return path.resolve(env.NUOS_CATALOGUE_INDEX_DIR);
+    // buildRoot is `<project-root>/docs/build`; two dirname() calls climb
+    // back to the project root.
+    const projectRoot = path.dirname(path.dirname(buildRoot));
+    return path.join(projectRoot, '.nuos-catalogue');
+}
+export function resolveWorkflowsPath(buildRoot, flag, ctx) {
+    if (typeof flag === 'string' && flag.length > 0)
+        return path.resolve(flag);
+    const env = ctxEnv(ctx);
+    if (env.NUOS_CATALOGUE_WORKFLOWS)
+        return path.resolve(env.NUOS_CATALOGUE_WORKFLOWS);
+    return path.join(resolveIndexDir(buildRoot, ctx), 'workflows.json');
+}
+export function resolveIndexPath(buildRoot, flag, ctx) {
+    if (typeof flag === 'string' && flag.length > 0)
+        return path.resolve(flag);
+    return path.join(resolveIndexDir(buildRoot, ctx), 'index.nv');
+}
+export function resolveHashPath(buildRoot, flag, ctx) {
+    if (typeof flag === 'string' && flag.length > 0)
+        return path.resolve(flag);
+    return path.join(resolveIndexDir(buildRoot, ctx), 'hashes.json');
+}
+/**
+ * Soft warning surfaced after a `migrate` or `regenerate` run: if the
+ * project has a `.gitignore` at its root and that `.gitignore` does
+ * NOT contain a `.nuos-catalogue/` entry, the workflow store appears
+ * as untracked. Returns a multi-line `note:` string when a warning
+ * should be printed, or null when silent.
+ *
+ * Silent when:
+ *   - the project has no `.gitignore` (it might not be a git repo)
+ *   - the gitignore already excludes `.nuos-catalogue/`
+ *   - the gitignore can't be read for any reason (be quiet, not noisy)
+ */
+export function gitignoreCatalogueNote(buildRoot, ctx) {
+    try {
+        const projectRoot = path.dirname(path.dirname(buildRoot));
+        const gitignorePath = path.join(projectRoot, '.gitignore');
+        if (!existsSync(gitignorePath))
+            return null;
+        const content = readFileSync(gitignorePath, 'utf8');
+        if (/^\s*\.nuos-catalogue\//m.test(content))
+            return null;
+        const indexDir = resolveIndexDir(buildRoot, ctx);
+        return ('note: the workflow store is at ' +
+            path.relative(projectRoot, indexDir) +
+            '/, but your .gitignore does not exclude .nuos-catalogue/.\n' +
+            '      Add this line to .gitignore so the per-machine JSON state stays out of commits:\n' +
+            '          .nuos-catalogue/');
+    }
+    catch {
+        return null;
+    }
+}

package/dist/runtime/ac-parse.js

@@ -160,15 +160,19 @@ export function extractForCompletion(rawMarkdown) {
  */
 function parseHistoryEvidence(rawMarkdown) {
     const result = new Map();
-    const historyHeadingIndex = rawMarkdown.indexOf('## Build catalogue history');
-    if (historyHeadingIndex === -1)
+    // Anchor the heading lookup to start-of-line so prose mentions inside
+    // code spans or paragraphs (e.g. a WU's notes log discussing the
+    // section by name) don't false-match the literal string.
+    const HEADING_RE = /^## Build catalogue history\s*$/m;
+    const headingMatch = HEADING_RE.exec(rawMarkdown);
+    if (!headingMatch)
         return result;
+    const historyHeadingIndex = headingMatch.index;
+    const headingLength = headingMatch[0].length;
     const sectionTail = rawMarkdown.slice(historyHeadingIndex);
     // Bound the history section at the next ## heading (if any).
-    const nextSectionMatch = /\n## \S/.exec(sectionTail.slice('## Build catalogue history'.length));
-    const sectionEnd = nextSectionMatch
-        ? '## Build catalogue history'.length + nextSectionMatch.index
-        : sectionTail.length;
+    const nextSectionMatch = /\n## \S/.exec(sectionTail.slice(headingLength));
+    const sectionEnd = nextSectionMatch ? headingLength + nextSectionMatch.index : sectionTail.length;
     const section = sectionTail.slice(0, sectionEnd);
     // Split into entries on the top-level `- **<timestamp>**` bullets.
     // Each entry runs until the next top-level bullet or end-of-section.

package/dist/runtime/markdown-edit.d.ts

@@ -49,5 +49,10 @@ export interface ChangeLogEntry {
  * Idempotence: each call appends; running the same workflow twice
  * appends twice. The audit chain in the workflow store is the
  * deduplicating source of truth.
+ *
+ * Heading detection is anchored to start-of-line via a regex so that
+ * prose mentions of the heading text inside code spans or paragraphs
+ * (e.g. a WU's notes log discussing the section by name) don't
+ * false-match and cause the entry to land in the wrong place.
  */
 export declare function appendChangeLog(rawMarkdown: string, entry: ChangeLogEntry): string;

package/dist/runtime/markdown-edit.js

@@ -64,10 +64,18 @@ export function insertStatusLine(rawMarkdown, newStatus) {
  * Idempotence: each call appends; running the same workflow twice
  * appends twice. The audit chain in the workflow store is the
  * deduplicating source of truth.
+ *
+ * Heading detection is anchored to start-of-line via a regex so that
+ * prose mentions of the heading text inside code spans or paragraphs
+ * (e.g. a WU's notes log discussing the section by name) don't
+ * false-match and cause the entry to land in the wrong place.
  */
 export function appendChangeLog(rawMarkdown, entry) {
     const heading = '## Build catalogue history';
-    const headingIndex = rawMarkdown.indexOf(heading);
+    const HEADING_RE = /^## Build catalogue history\s*$/m;
+    const headingMatch = HEADING_RE.exec(rawMarkdown);
+    const headingIndex = headingMatch ? headingMatch.index : -1;
+    const headingLength = headingMatch ? headingMatch[0].length : 0;
     const detailLines = [];
     if (entry.details)
         detailLines.push(`  - ${entry.details}`);
@@ -82,17 +90,16 @@ export function appendChangeLog(rawMarkdown, entry) {
         return `${rawMarkdown}${sep}\n${heading}\n\n${block}\n`;
     }
     // Find the end of the file (or the next section) and insert before that.
-    // Simplest: append the block immediately after the existing section's
-    // current content. We treat everything from `headingIndex` to the
-    // next H1/H2 boundary (or EOF) as the section.
+    // We treat everything from `headingIndex` to the next H1/H2 boundary
+    // (or EOF) as the section's body.
     const tail = rawMarkdown.slice(headingIndex);
-    const nextHeadingMatch = /\n##? \S/.exec(tail.slice(heading.length));
+    const nextHeadingMatch = /\n##? \S/.exec(tail.slice(headingLength));
     if (!nextHeadingMatch) {
         // History is the last section — append at end of file.
         const sep = rawMarkdown.endsWith('\n') ? '' : '\n';
         return `${rawMarkdown}${sep}${block}\n`;
     }
-    const splitAt = headingIndex + heading.length + nextHeadingMatch.index;
+    const splitAt = headingIndex + headingLength + nextHeadingMatch.index;
     const before = rawMarkdown.slice(0, splitAt);
     const after = rawMarkdown.slice(splitAt);
     const beforeHasTrailingNewline = before.endsWith('\n');

package/dist/runtime/mis-adapter.js

@@ -245,9 +245,14 @@ async function commitTickAC(store, catalogueRoot, intent) {
             throw err;
         }
     }
+    // criterionIndex is 0-based internally; the audit log uses 1-based
+    // numbering consistently across both the structural-tick path and the
+    // audit-log-only fallback, so users never see a mix of 0-based and
+    // 1-based references in their catalogue history.
+    const oneBased = payload.criterionIndex + 1;
     const summary = acText
-        ? `Acceptance criterion ${payload.criterionIndex + 1} ticked: "${acText}".`
-        : `Acceptance criterion at index ${payload.criterionIndex} ticked.`;
+        ? `Acceptance criterion ${oneBased} ticked: "${acText}".`
+        : `Acceptance criterion ${oneBased} ticked.`;
     const updatedMarkdown = appendChangeLog(workingMarkdown, {
         isoTimestamp: new Date().toISOString(),
         summary: structuralTick ? summary : `${summary} (audit-log-only — AC list not recognised)`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nusoft/nuos-build-catalogue",
-  "version": "0.12.0",
+  "version": "0.14.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,7 +19,7 @@
     "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",
+    "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",
     "typecheck": "tsc --noEmit",
     "index": "tsx src/cli.ts index",
     "search": "tsx src/cli.ts search"

package/templates/hooks/install-hooks.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+#
+# Install the catalogue's git hooks into .git/hooks/.
+#
+# Why this script (not husky):
+#   The nuos repo is a markdown catalogue, not an npm package. Adding a
+#   package.json + node_modules just to install hooks would be infrastructure
+#   tax for what is otherwise a doc repo. A small bash installer copies the
+#   hooks from the version-controlled scripts/hooks/ into .git/hooks/.
+#
+# Usage:
+#   bash scripts/install-hooks.sh
+#
+# Re-run any time scripts/hooks/ changes; the installer is idempotent.
+
+set -euo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+SOURCE="$REPO_ROOT/scripts/hooks"
+TARGET="$REPO_ROOT/.git/hooks"
+
+if [[ ! -d "$SOURCE" ]]; then
+  echo "✖ scripts/hooks/ not found; nothing to install" >&2
+  exit 1
+fi
+
+mkdir -p "$TARGET"
+
+installed=0
+for hook in "$SOURCE"/*; do
+  name="$(basename "$hook")"
+  cp "$hook" "$TARGET/$name"
+  chmod +x "$TARGET/$name"
+  installed=$((installed + 1))
+done
+
+echo "✓ installed $installed hook(s) into .git/hooks/"
+echo
+echo "Active rules (WU 111 enforcement):"
+echo "  • index-drift detection (work-units, decisions, open-questions, risks)"
+echo "  • active-decision modification BLOCK (was warning under WU 128 light-touch)"
+echo
+echo "To verify the install: \`git hook list\` (git ≥2.36) or \`ls .git/hooks/\`"
+echo "To uninstall: \`rm .git/hooks/pre-commit\`"

package/templates/hooks/post-commit

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+#
+# NuOS catalogue post-commit hook — auto-refresh the semantic-search index
+# after every commit that touched docs/build/**.
+#
+# Why this hook:
+#   `nuos-catalogue search` only finds what's in the NuVector index. The
+#   index is hash-based and incremental, but it doesn't update itself —
+#   you have to run `nuos-catalogue index` after meaningful changes for
+#   new content to be searchable. Running it manually is too easy to
+#   forget; the discipline argument that gave us the pre-commit hook
+#   (index-drift, accepted-decision immutability) applies equally here.
+#
+# Behaviour:
+#   - Skip if the just-landed commit did NOT touch docs/build/** (most
+#     code commits don't need a reindex)
+#   - Skip if `nuos-catalogue` isn't resolvable (the CLI may not be
+#     installed yet on a fresh clone; this hook should never block)
+#   - Otherwise: run the index in the BACKGROUND so the user's terminal
+#     isn't held while we embed. All output goes to .nuos-enforcement.log.
+#
+#   The hook respects two env vars:
+#     NUOS_CATALOGUE_INDEX_DIR   default: <repo>/.nuos-catalogue
+#     NUOS_CATALOGUE_OLLAMA_MODEL  passed through to the CLI
+#
+# This hook never blocks. If indexing fails (Ollama not running, model
+# not pulled, dimension mismatch with existing index), the error goes
+# to the log and the user can investigate. The commit itself already
+# landed by the time post-commit fires.
+
+set -uo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+LOG="$REPO_ROOT/.nuos-enforcement.log"
+
+dim()    { printf '\033[2m%s\033[0m\n' "$*"; }
+yellow() { printf '\033[33m%s\033[0m\n' "$*"; }
+
+# ---- Skip-paths --------------------------------------------------------
+
+# Skip if this project doesn't have a catalogue at all.
+if [[ ! -d "$REPO_ROOT/docs/build" ]]; then
+  exit 0
+fi
+
+# Skip if the just-landed commit didn't touch docs/build/**.
+if ! git diff-tree --no-commit-id --name-only -r HEAD 2>/dev/null | grep -q '^docs/build/'; then
+  exit 0
+fi
+
+# Resolve the CLI: prefer globally-installed `nuos-catalogue`; fall back
+# to `npx --yes` which fetches from npm on demand.
+INDEX_CMD=""
+if command -v nuos-catalogue >/dev/null 2>&1; then
+  INDEX_CMD="nuos-catalogue"
+elif command -v npx >/dev/null 2>&1; then
+  INDEX_CMD="npx --yes @nusoft/nuos-build-catalogue"
+else
+  yellow "[nuos:post-commit] neither nuos-catalogue nor npx found; skipping index refresh"
+  printf '%s | post-commit-skip | no CLI available\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" >> "$LOG"
+  exit 0
+fi
+
+# ---- Background index refresh ------------------------------------------
+
+# Default the index dir to project-local if the user hasn't set one.
+: "${NUOS_CATALOGUE_INDEX_DIR:=$REPO_ROOT/.nuos-catalogue}"
+export NUOS_CATALOGUE_INDEX_DIR
+
+# Detach from the terminal so the post-commit returns immediately. All
+# output (stdout + stderr) goes to the enforcement log so the user can
+# tail it if they want to see progress.
+(
+  start=$(date +%s)
+  printf '%s | post-commit-index | start (model=%s, dir=%s)\n' \
+    "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" \
+    "${NUOS_CATALOGUE_OLLAMA_MODEL:-default}" \
+    "$NUOS_CATALOGUE_INDEX_DIR" \
+    >> "$LOG"
+
+  if cd "$REPO_ROOT" && $INDEX_CMD index >> "$LOG" 2>&1; then
+    end=$(date +%s)
+    printf '%s | post-commit-index | done in %ss\n' \
+      "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" \
+      $((end - start)) \
+      >> "$LOG"
+  else
+    printf '%s | post-commit-index | FAILED (see lines above in %s)\n' \
+      "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" \
+      "$(basename "$LOG")" \
+      >> "$LOG"
+  fi
+) </dev/null >/dev/null 2>&1 &
+disown 2>/dev/null || true
+
+dim "[nuos:post-commit] index refresh started in background — see .nuos-enforcement.log"