@nusoft/nuos-build-catalogue 0.19.0 → 0.20.0

package/dist/cli.js

@@ -460,7 +460,17 @@ async function main() {
             // when the user switched machines and needs to pull the model
             // freshly. Same orchestrator that `init` calls internally.
             const { runLlmSetup } = await import('./setup/run-llm-setup.js');
+            const { ensureIndexBuilt } = await import('./setup/auto-index.js');
             const result = await runLlmSetup({ nonInteractive: false });
+            // After the LLM stack is ready, auto-build the search index when
+            // it isn't already present. Same helper init and install-protocols
+            // use — keeps the three commands aligned on "after this finishes
+            // the project is search-ready".
+            if (result.kind === 'already_ready' ||
+                result.kind === 'pulled_only' ||
+                result.kind === 'installed_and_pulled') {
+                await ensureIndexBuilt({});
+            }
             // Most failure paths emit guidance in-band; we exit non-zero only
             // when a pull actually failed (so CI scripting can branch on it).
             const exitCode = result.kind === 'pull_failed' || result.kind === 'install_failed' ? 1 : 0;

package/dist/commands/init.js

@@ -211,6 +211,7 @@ export async function cmdInit(prompt, options = {}) {
     // `nuos-catalogue setup-llm` later.
     if (!options.noLlm) {
         const { runLlmSetup } = await import('../setup/run-llm-setup.js');
+        const { ensureIndexBuilt } = await import('../setup/auto-index.js');
         await runLlmSetup({
             // The setup module writes its own progress directly to stderr; we
             // don't route through `prompt.print` because the in-place progress
@@ -224,6 +225,17 @@ export async function cmdInit(prompt, options = {}) {
             // so this is safe in unattended runs too.
             nonInteractive: false,
         });
+        // After LLM setup succeeds, auto-build the first search index. On a
+        // fresh project this is ~30s of starter-kit boilerplate; trivial,
+        // and finishing here means `search` works out of the box. When the
+        // LLM stack isn't ready, `ensureIndexBuilt` skips with a hint
+        // pointing back to setup-llm.
+        const indexResult = await ensureIndexBuilt({ cwd });
+        if (indexResult.kind === 'skipped_llm_not_ready') {
+            prompt.print('');
+            prompt.print(`  · Skipping first-index build: ${indexResult.reason}.`);
+            prompt.print(`  · ${indexResult.hint}`);
+        }
     }
     else {
         prompt.print('');
@@ -274,8 +286,62 @@ export async function cmdInstallProtocols(prompt, options = {}) {
     prompt.print('');
     prompt.print(`Refreshing swarm agent definitions (.claude/agents/):`);
     await installAgents(cwd, (msg) => prompt.print(msg));
+    // Quick non-interactive probe of the local-inference stack (WU 135).
+    // `install-protocols` is the natural upgrade path for existing
+    // projects, so we surface the LLM status here too — but as a status
+    // report rather than the full install/pull flow (which is what
+    // `setup-llm` is for). This keeps install-protocols fast and
+    // script-safe while making the LLM state visible without the user
+    // needing to know about a separate command.
+    prompt.print('');
+    prompt.print('Checking local semantic search (Ollama + qwen3-embedding:0.6b):');
+    await reportLlmStatus((msg) => prompt.print(`  ${msg}`));
+    // Auto-build the search index when the LLM is ready but the index
+    // isn't present yet (typical upgrade-path state: pre-0.19 install +
+    // someone just added docs/build/ content). When the index already
+    // exists this is a no-op; when the LLM isn't ready the helper skips
+    // with a hint that's already printed by reportLlmStatus.
+    const { ensureIndexBuilt } = await import('../setup/auto-index.js');
+    const indexResult = await ensureIndexBuilt({ cwd });
+    if (indexResult.kind === 'just_built') {
+        prompt.print(`  ✓ Built search index (${indexResult.indexed} files, ${indexResult.chunks} chunks).`);
+    }
     return { output: '', exitCode: 0 };
 }
+/**
+ * Quick probe + status print for the LLM stack. Non-interactive: never
+ * prompts, never installs, never pulls. The full install/pull flow
+ * lives in `setup-llm`; this is the "what's the current state?" report.
+ *
+ * Times out after ~1.5s when Ollama isn't running so the command stays
+ * snappy on machines that haven't set up local inference yet.
+ */
+async function reportLlmStatus(log) {
+    const { narrowPlatform } = await import('../setup/types.js');
+    const { detectOllamaApi, detectModelPresent } = await import('../setup/ollama-detect.js');
+    const { DEFAULT_EMBEDDING_MODEL } = await import('../setup/run-llm-setup.js');
+    const platform = narrowPlatform(process.platform);
+    const apiHost = process.env.NUOS_CATALOGUE_OLLAMA_HOST ?? 'http://localhost:11434';
+    const modelId = process.env.NUOS_CATALOGUE_OLLAMA_MODEL ?? DEFAULT_EMBEDDING_MODEL;
+    const api = await detectOllamaApi(apiHost);
+    if (!api.reachable) {
+        log(`✗ Ollama is not running at ${apiHost}`);
+        log('  Run `nuos-catalogue setup-llm` for guided install + pull.');
+        return;
+    }
+    log(`✓ Ollama is running at ${apiHost}`);
+    const model = await detectModelPresent(apiHost, modelId);
+    if (!model.present) {
+        log(`✗ ${modelId} is not pulled`);
+        log('  Run `nuos-catalogue setup-llm` to download it (~600 MB).');
+        return;
+    }
+    log(`✓ ${modelId} is pulled (~600 MB)`);
+    log(`Semantic search is ready. Try \`nuos-catalogue search "your query"\` after the first index.`);
+    // Suppress the unused-variable warning while keeping platform available
+    // for future per-OS hints (e.g. "Ollama runs in the menu bar on macOS").
+    void platform;
+}
 // ---------------------------------------------------------------------------
 // installHooks — copy bundled hook sources into the consumer + activate them
 // ---------------------------------------------------------------------------

package/dist/setup/auto-index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared helper that runs the first search index build automatically
+ * from `init`, `install-protocols`, and `setup-llm`.
+ *
+ * Gated on the LLM stack being ready (Ollama + the configured embedding
+ * model). If the LLM isn't ready, this helper returns a `skipped_llm`
+ * result with a hint string the caller prints. The hint references
+ * `setup-llm` so the user has a clear path forward.
+ *
+ * Indexing on a fresh project takes ~30s — small enough that auto-
+ * running on first install is friendlier than asking. Subsequent calls
+ * are incremental via the per-file SHA hashes, so re-running on an
+ * existing index is cheap.
+ *
+ * @module setup/auto-index
+ */
+/** Outcome of an auto-index attempt. */
+export type AutoIndexResult = {
+    kind: 'already_built';
+    indexPath: string;
+} | {
+    kind: 'just_built';
+    indexPath: string;
+    indexed: number;
+    chunks: number;
+    durationMs: number;
+} | {
+    kind: 'skipped_llm_not_ready';
+    reason: string;
+    hint: string;
+} | {
+    kind: 'skipped_no_catalogue';
+} | {
+    kind: 'failed';
+    error: string;
+};
+export interface AutoIndexOptions {
+    /** Project root for path resolution. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Output sink — defaults to process.stderr. */
+    out?: (text: string) => void;
+    /** Force a full reindex even if the index file already exists. */
+    force?: boolean;
+}
+/**
+ * Build the first search index when conditions allow. Idempotent: returns
+ * `already_built` and prints nothing when the index file exists (unless
+ * `force` is set). Returns `skipped_llm_not_ready` with a hint when the
+ * Ollama probe fails — the caller prints the hint and the user runs
+ * `setup-llm` to fix things.
+ *
+ * Never throws on user-facing failures.
+ */
+export declare function ensureIndexBuilt(opts?: AutoIndexOptions): Promise<AutoIndexResult>;

package/dist/setup/auto-index.js

@@ -0,0 +1,116 @@
+/**
+ * Shared helper that runs the first search index build automatically
+ * from `init`, `install-protocols`, and `setup-llm`.
+ *
+ * Gated on the LLM stack being ready (Ollama + the configured embedding
+ * model). If the LLM isn't ready, this helper returns a `skipped_llm`
+ * result with a hint string the caller prints. The hint references
+ * `setup-llm` so the user has a clear path forward.
+ *
+ * Indexing on a fresh project takes ~30s — small enough that auto-
+ * running on first install is friendlier than asking. Subsequent calls
+ * are incremental via the per-file SHA hashes, so re-running on an
+ * existing index is cheap.
+ *
+ * @module setup/auto-index
+ */
+import { existsSync } from 'node:fs';
+import { resolveBuildRoot, resolveCatalogueRoot, resolveHashPath, resolveIndexPath, } from '../path-resolution.js';
+import { DEFAULT_OLLAMA_HOST, detectModelPresent, detectOllamaApi } from './ollama-detect.js';
+import { DEFAULT_EMBEDDING_MODEL } from './run-llm-setup.js';
+/**
+ * Build the first search index when conditions allow. Idempotent: returns
+ * `already_built` and prints nothing when the index file exists (unless
+ * `force` is set). Returns `skipped_llm_not_ready` with a hint when the
+ * Ollama probe fails — the caller prints the hint and the user runs
+ * `setup-llm` to fix things.
+ *
+ * Never throws on user-facing failures.
+ */
+export async function ensureIndexBuilt(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const out = opts.out ?? ((text) => process.stderr.write(text));
+    // Resolve where the index file lives without forcing the LLM stack to
+    // load — path resolution is cheap and offline. When the project has
+    // no `docs/build/` yet (e.g. install-protocols invoked in a non-
+    // scaffolded directory), resolveBuildRoot throws — we treat that as a
+    // silent no-op, since there is nothing meaningful to index.
+    const ctx = { cwd, env: process.env };
+    let buildRoot;
+    let catalogueRoot;
+    let indexPath;
+    let hashPath;
+    try {
+        buildRoot = resolveBuildRoot(undefined, ctx);
+        catalogueRoot = resolveCatalogueRoot(undefined, ctx);
+        indexPath = resolveIndexPath(buildRoot, undefined, ctx);
+        hashPath = resolveHashPath(buildRoot, undefined, ctx);
+    }
+    catch {
+        return { kind: 'skipped_no_catalogue' };
+    }
+    // Fast path: index file already exists and we're not forcing a rebuild.
+    if (existsSync(indexPath) && !opts.force) {
+        return { kind: 'already_built', indexPath };
+    }
+    // Probe the LLM stack — index requires Ollama + the model. If either
+    // is missing, skip with a hint pointing at setup-llm.
+    const apiHost = process.env.NUOS_CATALOGUE_OLLAMA_HOST ?? DEFAULT_OLLAMA_HOST;
+    const modelId = process.env.NUOS_CATALOGUE_OLLAMA_MODEL ?? DEFAULT_EMBEDDING_MODEL;
+    const api = await detectOllamaApi(apiHost);
+    if (!api.reachable) {
+        return {
+            kind: 'skipped_llm_not_ready',
+            reason: `Ollama is not running at ${apiHost}`,
+            hint: 'Run `nuos-catalogue setup-llm` to set up local semantic search, then re-run `nuos-catalogue index`.',
+        };
+    }
+    const model = await detectModelPresent(apiHost, modelId);
+    if (!model.present) {
+        return {
+            kind: 'skipped_llm_not_ready',
+            reason: `${modelId} is not pulled`,
+            hint: 'Run `nuos-catalogue setup-llm` to pull the embedding model (~600 MB), then re-run `nuos-catalogue index`.',
+        };
+    }
+    // LLM is ready. Build the index. We import lazily so the cold-start
+    // path of `install-protocols` (where the index usually already exists)
+    // doesn't pay the embedder-loading cost.
+    out('Building search index for docs/build/ … (first run may take ~30 seconds)\n');
+    try {
+        const { selectEmbedderFromEnv } = await import('../embedder/select.js');
+        const { openStore } = await import('../store/open.js');
+        const { runIndex } = await import('../indexer/upsert.js');
+        const embedder = await selectEmbedderFromEnv();
+        const store = await openStore({ storagePath: indexPath, dimensions: embedder.dimensions });
+        try {
+            const report = await runIndex({
+                catalogueRoot,
+                hashFilePath: hashPath,
+                store,
+                embedder,
+                force: Boolean(opts.force),
+                dryRun: false,
+            });
+            out(`✓ Indexed ${report.indexed} file(s), ${report.chunks} chunks embedded in ` +
+                `${(report.durationMs / 1000).toFixed(1)}s\n`);
+            return {
+                kind: 'just_built',
+                indexPath,
+                indexed: report.indexed,
+                chunks: report.chunks,
+                durationMs: report.durationMs,
+            };
+        }
+        finally {
+            // Unload-after-use commitment — embedder releases the model.
+            await embedder.dispose();
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        out(`\n✗ Index build failed: ${message}\n`);
+        out('Re-run `nuos-catalogue index` manually to retry.\n');
+        return { kind: 'failed', error: message };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nusoft/nuos-build-catalogue",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "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": {

package/scripts/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"

package/scripts/hooks/pre-commit

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+#
+# NuOS catalogue pre-commit hook (WU 111 enforcement phase).
+#
+# Catches drift before commit. After WU 111's Phase J ship, the
+# accepted-decision rule has flipped from warning → block (per the
+# pack's narrower-than-originally-planned enforcement scope, recorded
+# in WU 111's "Forward-compatibility commitments" section). Other
+# rules described in WU 128's original aggressive list are NOT shipping
+# — distinguishing tool-written from human-written content was deemed
+# overengineering for a planning-artefact catalogue.
+#
+# Active rules:
+#   1. index-drift detection — every WU/decision/open-question/risk file
+#      must have a matching row in its _index.md (and vice versa)
+#   2. active-decision modification block — modifying a committed
+#      `accepted` decision file is BLOCKED (not just warned). The
+#      discipline is to write a superseding D-NNN+1 and link forward.
+#      To deliberately fix a typo or link in an accepted decision,
+#      use `git commit --no-verify` (CLAUDE.md prohibits this for
+#      substantive changes; reserve it for typo-only fixes).
+#
+# Sentinel-protected sections (e.g. STATE.md's `nuos:sentinel`) remain
+# protected via the existing `.claude/hooks/check-catalogue-write.sh`
+# Claude Code hook. That rule continues unchanged at WU 111 ship.
+#
+# Bypass: this hook respects --no-verify like any other. The CLAUDE.md
+# policy explicitly prohibits --no-verify use for substantive changes;
+# the technical block fires at the CI server-side check (a future WU).
+
+set -uo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+ENFORCEMENT_LOG="$REPO_ROOT/.nuos-enforcement.log"
+EXIT_CODE=0
+
+red()    { printf '\033[31m%s\033[0m\n' "$*"; }
+yellow() { printf '\033[33m%s\033[0m\n' "$*"; }
+green()  { printf '\033[32m%s\033[0m\n' "$*"; }
+dim()    { printf '\033[2m%s\033[0m\n' "$*"; }
+
+log_event() {
+  printf '%s | %s | %s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" "$1" "$2" >> "$ENFORCEMENT_LOG"
+}
+
+# ---------- Generic index-drift checker ---------------------------------
+#
+# Args:
+#   $1 — kind label (for messages)
+#   $2 — directory (relative to repo root)
+#   $3 — _index.md path (relative to repo root)
+#   $4 — filename regex (matches IDs the directory contains)
+#   $5 — index-row ID regex (a Perl-compatible regex that anchors on the
+#        leftmost column of an index table row)
+#
+# The two regexes must extract the SAME set of IDs (e.g. "001", "030g",
+# "D042") so set comparison works.
+
+check_index_drift() {
+  local kind="$1" dir="$2" index="$3" file_regex="$4" row_regex="$5"
+
+  if [[ ! -d "$REPO_ROOT/$dir" ]]; then return 0; fi
+  if [[ ! -f "$REPO_ROOT/$index" ]]; then return 0; fi
+
+  # IDs extracted from filenames in the directory (top-level + one subdir
+  # like done/, resolved/, superseded/)
+  local ids_in_tree
+  ids_in_tree=$(cd "$REPO_ROOT/$dir" && {
+    find . -maxdepth 2 -type f -name "*.md" \
+      -not -name "_index.md" \
+      -not -name "*-template.md" 2>/dev/null \
+      | sed -nE "$file_regex" \
+      | sort -u
+  })
+
+  # IDs extracted from leftmost column of table rows in the index
+  local ids_in_index
+  ids_in_index=$(sed -nE "$row_regex" "$REPO_ROOT/$index" | sort -u)
+
+  local missing_from_index
+  missing_from_index=$(comm -23 <(printf '%s\n' "$ids_in_tree") <(printf '%s\n' "$ids_in_index"))
+
+  if [[ -n "$missing_from_index" ]]; then
+    red "✖ index-drift ($kind): on disk but missing from $index:"
+    while IFS= read -r id; do echo "    — $id"; done <<< "$missing_from_index"
+    log_event "index-drift" "$kind missing from index: $(echo "$missing_from_index" | tr '\n' ',')"
+    EXIT_CODE=1
+  fi
+}
+
+dim "[nuos:pre-commit] index-drift check"
+
+# Note: BSD sed (macOS default) is fussy about `|` as both delimiter and
+# regex content. Using `#` as the s/// delimiter sidesteps the collision.
+
+# Work units: filenames are NNN-slug.md or NNNa-slug.md (with optional letter).
+# Index rows are `| NNN |` or `| NNNa |` in the leftmost column.
+check_index_drift \
+  "work-units" \
+  "docs/build/work-units" \
+  "docs/build/work-units/_index.md" \
+  's#^\./(done/)?([0-9]{3}[a-z]?)-[^/]*\.md$#\2#p' \
+  's#^\| ([0-9]{3}[a-z]?) \|.*$#\1#p'
+
+# Decisions: filenames are DNNN-slug.md.
+# Index rows: `| DNNN |` or `| [DNNN](...) |`.
+check_index_drift \
+  "decisions" \
+  "docs/build/decisions" \
+  "docs/build/decisions/_index.md" \
+  's#^\./(done/|superseded/)?(D[0-9]{3})-[^/]*\.md$#\2#p' \
+  's#^\| \[?(D[0-9]{3}).*$#\1#p'
+
+# Open questions: filenames are QNNN-slug.md.
+check_index_drift \
+  "open-questions" \
+  "docs/build/open-questions" \
+  "docs/build/open-questions/_index.md" \
+  's#^\./(resolved/)?(Q[0-9]{3})-[^/]*\.md$#\2#p' \
+  's#^\| \[?(Q[0-9]{3}).*$#\1#p'
+
+# Risks: per current convention, individual risk files are inline in
+# risks/_index.md (no per-risk .md files yet). Skip the check entirely
+# until that pattern changes.
+if compgen -G "$REPO_ROOT/docs/build/risks/R[0-9][0-9][0-9]-*.md" > /dev/null; then
+  check_index_drift \
+    "risks" \
+    "docs/build/risks" \
+    "docs/build/risks/_index.md" \
+    's#^\./(R[0-9]{3})-[^/]*\.md$#\1#p' \
+    's#^\| \[?(R[0-9]{3}).*$#\1#p'
+fi
+
+# ---------- Rule 2: active-decision modification block (WU 111 ship) ---
+
+dim "[nuos:pre-commit] active-decision modification check"
+modified_decisions=$(git diff --cached --name-only --diff-filter=M \
+  | grep -E '^docs/build/decisions/D[0-9]+.*\.md$' \
+  | grep -v '/superseded/' \
+  || true)
+
+if [[ -n "$modified_decisions" ]]; then
+  red "✖ active-decision modification — BLOCKED (WU 111 enforcement):"
+  while IFS= read -r f; do echo "    — $f"; done <<< "$modified_decisions"
+  red "  Decisions are immutable once accepted. The discipline is to write a"
+  red "  superseding D-NNN+1 and link forward. Use:"
+  red "    nuos-catalogue decision supersede <target> --by=<new-D> --reason=\"...\""
+  red ""
+  red "  If this edit is a non-substantive typo fix or link cleanup that does"
+  red "  not change the decision's meaning, you may bypass this block with"
+  red "  --no-verify. CLAUDE.md prohibits --no-verify for substantive changes."
+  log_event "active-decision-block" "$(echo "$modified_decisions" | tr '\n' ',')"
+  EXIT_CODE=1
+fi
+
+# ---------- Result ------------------------------------------------------
+
+if [[ $EXIT_CODE -eq 0 ]]; then
+  green "[nuos:pre-commit] all rules pass (WU 111 enforcement)"
+  log_event "pre-commit-pass" "$(git diff --cached --name-only | wc -l | tr -d ' ') files"
+fi
+exit $EXIT_CODE

package/scripts/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\`"