@nusoft/nuos-build-catalogue 0.20.0 → 0.21.0

package/dist/cli.js

@@ -159,6 +159,27 @@ async function cmdRegisterDispatch(command, positional, flags) {
         process.exit(2);
     }
     const action = positional[0];
+    // WU 136 — `wu start` / `wu end` / `wu current` are file-only commands
+    // (manage the active-WU marker for the PreToolUse hook). They do NOT
+    // need the workflow store, so handle them BEFORE the store is opened —
+    // this also keeps them fast and avoids requiring a fully-migrated
+    // catalogue to declare an active WU.
+    if (command === 'wu' && (action === 'start' || action === 'end' || action === 'current')) {
+        const { cmdWuStart, cmdWuEnd, cmdWuCurrent } = await import('./commands/wu-active.js');
+        let result;
+        if (action === 'start') {
+            result = cmdWuStart(positional[1], { cwd: process.cwd() });
+        }
+        else if (action === 'end') {
+            result = cmdWuEnd({ cwd: process.cwd() });
+        }
+        else {
+            result = cmdWuCurrent({ cwd: process.cwd() });
+        }
+        console.log(result.output);
+        process.exit(result.exitCode);
+        return;
+    }
     const buildRoot = resolveBuildRoot(flags['build-root']);
     const workflowsPath = resolveWorkflowsPath(buildRoot, flags['workflows']);
     const store = await openWorkflowStore(workflowsPath);
@@ -368,6 +389,8 @@ Usage:
                           (run the LLM-setup phase outside 'init': detect Ollama, offer to install where reliable, pull qwen3-embedding:0.6b with a progress bar. Idempotent — safe to re-run)
   nuos-catalogue install-protocols
                           (refresh .claude/commands/<protocols> from this CLI's bundled canonical bodies)
+  nuos-catalogue install-hooks
+                          (WU 136 — install the Claude PreToolUse hook that gates sibling-repo writes on a declared active WU; idempotent)
 
   nuos-catalogue index    [--force] [--dry-run] [--catalogue=<dir>]
   nuos-catalogue search   "<query>" [--kind=<file_kind>] [--status=<s>] [--limit=N] [--json]
@@ -381,6 +404,12 @@ Usage:
   nuos-catalogue wu        advance   <handle> --to=<status> [--reason="..."]
   nuos-catalogue wu        tick      <handle> --index=N --evidence="..."
                           (--index is 1-based: --index=1 ticks the first AC)
+  nuos-catalogue wu        start     <handle>
+                          (WU 136 — declare this WU as the active one for sibling-repo writes; required by the install-hooks gate)
+  nuos-catalogue wu        end
+                          (clear the active-WU marker)
+  nuos-catalogue wu        current
+                          (print the active WU handle, or "(none)")
   nuos-catalogue decision  list      [--status=<s>] [--limit=N] [--json]
   nuos-catalogue decision  show      <handle> [--json]
   nuos-catalogue decision  create    (interactive)
@@ -490,6 +519,16 @@ async function main() {
             }
             break;
         }
+        case 'install-hooks': {
+            // WU 136 — install the Claude PreToolUse hook that gates
+            // sibling-repo writes on a declared active WU.
+            const { cmdInstallClaudeHooks } = await import('./commands/install-claude-hooks.js');
+            const result = cmdInstallClaudeHooks({ cwd: process.cwd() });
+            if (result.output)
+                console.log(result.output);
+            process.exit(result.exitCode);
+            break;
+        }
         case 'migrate':
             await cmdMigrate(args.flags);
             break;

package/dist/commands/init.js

@@ -296,16 +296,13 @@ export async function cmdInstallProtocols(prompt, options = {}) {
     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.
+    // Auto-build/refresh the search index when the LLM is ready. The
+    // indexer is incremental via per-file SHA hashes: a no-change project
+    // takes ~1s, a project with N changed files takes O(N) embed calls.
+    // When the LLM stack isn't ready the helper skips silently — the
+    // status was already reported above 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).`);
-    }
+    await ensureIndexBuilt({ cwd });
     return { output: '', exitCode: 0 };
 }
 /**

package/dist/commands/install-claude-hooks.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `install-hooks` — copy the package's Claude Code PreToolUse hook
+ * into the consumer's `.claude/hooks/`, wire it into the consumer's
+ * `.claude/settings.json`, and add the active-WU marker file to
+ * `.gitignore` so the per-session marker doesn't pollute commits.
+ *
+ * Idempotent. Safe to re-run after package upgrades — the hook script
+ * is overwritten, the settings entry is added only if missing, and the
+ * gitignore line is appended only if not present.
+ *
+ * @module commands/install-claude-hooks
+ */
+export interface CommandResult {
+    output: string;
+    exitCode: number;
+}
+export interface InstallClaudeHooksOptions {
+    cwd?: string;
+    /** Override the path the templates are resolved from (testing only). */
+    templatesDir?: string;
+}
+/**
+ * Idempotently install the Claude PreToolUse hook into the project at
+ * `cwd`. Returns a CommandResult describing what was done.
+ */
+export declare function cmdInstallClaudeHooks(opts?: InstallClaudeHooksOptions): CommandResult;
+export declare function addPreToolUseHook(settings: Record<string, unknown>, matcher: string, command: string): {
+    value: Record<string, unknown>;
+    changed: boolean;
+};
+export declare function ensureGitignoreEntry(path: string, line: string): boolean;

package/dist/commands/install-claude-hooks.js

@@ -0,0 +1,149 @@
+/**
+ * `install-hooks` — copy the package's Claude Code PreToolUse hook
+ * into the consumer's `.claude/hooks/`, wire it into the consumer's
+ * `.claude/settings.json`, and add the active-WU marker file to
+ * `.gitignore` so the per-session marker doesn't pollute commits.
+ *
+ * Idempotent. Safe to re-run after package upgrades — the hook script
+ * is overwritten, the settings entry is added only if missing, and the
+ * gitignore line is appended only if not present.
+ *
+ * @module commands/install-claude-hooks
+ */
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const HOOK_FILENAME = "check-implementation-write.sh";
+const SETTINGS_MATCHER = "Write|Edit|MultiEdit|NotebookEdit";
+const SETTINGS_COMMAND = `bash .claude/hooks/${HOOK_FILENAME}`;
+/**
+ * Resolve the path to the bundled `templates/claude-hooks/` directory.
+ * When running from `dist/` (the published package) the templates dir
+ * sits at `../templates/claude-hooks/` relative to the compiled JS.
+ * When running from source (tsx during development) it's at
+ * `../../templates/claude-hooks/` relative to this file.
+ */
+function resolveTemplatesDir() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // Look at sibling-of-parent first (compiled dist/commands/ → dist/../templates/),
+    // then grandparent-of-parent (src/commands/ → repo-root/templates/).
+    const candidates = [
+        resolve(here, "..", "..", "templates", "claude-hooks"),
+        resolve(here, "..", "templates", "claude-hooks"),
+    ];
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    // Last resort: return the first candidate so the error message names
+    // a real-ish path.
+    return candidates[0];
+}
+/**
+ * Idempotently install the Claude PreToolUse hook into the project at
+ * `cwd`. Returns a CommandResult describing what was done.
+ */
+export function cmdInstallClaudeHooks(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const templatesDir = opts.templatesDir ?? resolveTemplatesDir();
+    const srcHook = join(templatesDir, HOOK_FILENAME);
+    if (!existsSync(srcHook)) {
+        return {
+            output: `✖ nuos: hook template not found at ${srcHook}\n   The package may be installed incorrectly. Try reinstalling.`,
+            exitCode: 1,
+        };
+    }
+    const lines = [];
+    // 1. Copy the hook script into .claude/hooks/.
+    const hooksDir = join(cwd, ".claude", "hooks");
+    if (!existsSync(hooksDir))
+        mkdirSync(hooksDir, { recursive: true });
+    const destHook = join(hooksDir, HOOK_FILENAME);
+    copyFileSync(srcHook, destHook);
+    // Mark executable. bash is invoked explicitly via the matcher's
+    // `command`, but the exec bit helps when the hook is invoked
+    // directly during debugging.
+    try {
+        chmodSync(destHook, 0o755);
+    }
+    catch {
+        // chmod is best-effort on filesystems that don't support it.
+    }
+    lines.push(`  ✓ installed hook → .claude/hooks/${HOOK_FILENAME}`);
+    // 2. Merge into .claude/settings.json. We add a PreToolUse matcher
+    //    entry only if no entry with the same command already exists.
+    const settingsPath = join(cwd, ".claude", "settings.json");
+    const settings = readJsonOrEmpty(settingsPath);
+    const updated = addPreToolUseHook(settings, SETTINGS_MATCHER, SETTINGS_COMMAND);
+    if (updated.changed) {
+        writeFileSync(settingsPath, JSON.stringify(updated.value, null, 2) + "\n", "utf8");
+        lines.push("  ✓ updated .claude/settings.json (PreToolUse entry added)");
+    }
+    else {
+        lines.push("  · .claude/settings.json already has the PreToolUse entry");
+    }
+    // 3. Add the active-WU marker to .gitignore.
+    const gitignorePath = join(cwd, ".gitignore");
+    const addedGitignore = ensureGitignoreEntry(gitignorePath, ".nuos-catalogue/active-wu");
+    if (addedGitignore) {
+        lines.push("  ✓ added .nuos-catalogue/active-wu to .gitignore");
+    }
+    else {
+        lines.push("  · .nuos-catalogue/active-wu already in .gitignore");
+    }
+    return {
+        output: [
+            "nuos: Claude Code hooks installed.",
+            ...lines,
+            "",
+            "Next: declare an active work unit before substantive sibling-repo work:",
+            "    nuos-catalogue wu start <handle>",
+        ].join("\n"),
+        exitCode: 0,
+    };
+}
+// ── helpers ─────────────────────────────────────────────────────────────
+function readJsonOrEmpty(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function addPreToolUseHook(settings, matcher, command) {
+    // Defensive copy so callers can't accidentally see in-place mutation.
+    const next = { ...settings };
+    const hooksField = next.hooks ?? {};
+    const preToolUse = hooksField.PreToolUse ?? [];
+    // Already present? Check by command string (any matcher).
+    for (const entry of preToolUse) {
+        for (const h of entry.hooks ?? []) {
+            if (h.command === command) {
+                return { value: next, changed: false };
+            }
+        }
+    }
+    const newEntry = {
+        matcher,
+        hooks: [{ type: "command", command }],
+    };
+    const newPreToolUse = [...preToolUse, newEntry];
+    const newHooks = { ...hooksField, PreToolUse: newPreToolUse };
+    next.hooks = newHooks;
+    return { value: next, changed: true };
+}
+export function ensureGitignoreEntry(path, line) {
+    let body = "";
+    if (existsSync(path)) {
+        body = readFileSync(path, "utf8");
+    }
+    const lines = body.split("\n").map((l) => l.trim());
+    if (lines.includes(line))
+        return false;
+    const newBody = body.endsWith("\n") || body.length === 0 ? body + line + "\n" : body + "\n" + line + "\n";
+    writeFileSync(path, newBody, "utf8");
+    return true;
+}

package/dist/commands/wu-active.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `wu start` / `wu end` / `wu current` — manage the active-WU marker
+ * consumed by the Claude PreToolUse hook (WU 136).
+ *
+ * The marker is a single-line file at `.nuos-catalogue/active-wu`
+ * containing the handle of the WU currently being implemented. The hook
+ * reads it to decide whether a sibling-repo write is allowed.
+ *
+ * These commands are intentionally minimal — file read / write / unlink
+ * with friendly stdout. No workflow-store interaction, no validation of
+ * whether the handle resolves to a real WU. Validation could be added
+ * later if the unverified-handle pattern becomes a problem in practice;
+ * today's risk is low because the operator types the handle themselves.
+ *
+ * @module commands/wu-active
+ */
+export interface CommandResult {
+    output: string;
+    exitCode: number;
+}
+export interface WuActiveOptions {
+    /** Project root. Defaults to process.cwd(). */
+    cwd?: string;
+}
+/** Compute the path to the active-WU marker for a given project root. */
+export declare function activeWuMarkerPath(cwd: string): string;
+/**
+ * `wu start <handle>` — write the handle into the marker. Creates the
+ * `.nuos-catalogue/` directory if it doesn't yet exist (idempotent).
+ *
+ * Overwrites any existing marker without ceremony — the operator's
+ * `start` is authoritative. If they want to know the current value
+ * before overwriting, they use `wu current`.
+ */
+export declare function cmdWuStart(handle: string | undefined, opts?: WuActiveOptions): CommandResult;
+/**
+ * `wu end` — remove the marker. Succeeds silently if no marker is
+ * present (idempotent: stopping a stopped state is fine).
+ */
+export declare function cmdWuEnd(opts?: WuActiveOptions): CommandResult;
+/**
+ * `wu current` — print the current active WU handle or `(none)`.
+ * Always exits 0; absence is not an error.
+ */
+export declare function cmdWuCurrent(opts?: WuActiveOptions): CommandResult;

package/dist/commands/wu-active.js

@@ -0,0 +1,83 @@
+/**
+ * `wu start` / `wu end` / `wu current` — manage the active-WU marker
+ * consumed by the Claude PreToolUse hook (WU 136).
+ *
+ * The marker is a single-line file at `.nuos-catalogue/active-wu`
+ * containing the handle of the WU currently being implemented. The hook
+ * reads it to decide whether a sibling-repo write is allowed.
+ *
+ * These commands are intentionally minimal — file read / write / unlink
+ * with friendly stdout. No workflow-store interaction, no validation of
+ * whether the handle resolves to a real WU. Validation could be added
+ * later if the unverified-handle pattern becomes a problem in practice;
+ * today's risk is low because the operator types the handle themselves.
+ *
+ * @module commands/wu-active
+ */
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Compute the path to the active-WU marker for a given project root. */
+export function activeWuMarkerPath(cwd) {
+    return join(cwd, ".nuos-catalogue", "active-wu");
+}
+/**
+ * `wu start <handle>` — write the handle into the marker. Creates the
+ * `.nuos-catalogue/` directory if it doesn't yet exist (idempotent).
+ *
+ * Overwrites any existing marker without ceremony — the operator's
+ * `start` is authoritative. If they want to know the current value
+ * before overwriting, they use `wu current`.
+ */
+export function cmdWuStart(handle, opts = {}) {
+    if (!handle || handle.trim().length === 0) {
+        return {
+            output: "Usage: nuos-catalogue wu start <handle>",
+            exitCode: 2,
+        };
+    }
+    const cwd = opts.cwd ?? process.cwd();
+    const marker = activeWuMarkerPath(cwd);
+    const dir = dirname(marker);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(marker, handle.trim() + "\n", "utf8");
+    return {
+        output: `nuos: active work unit set to "${handle.trim()}"`,
+        exitCode: 0,
+    };
+}
+/**
+ * `wu end` — remove the marker. Succeeds silently if no marker is
+ * present (idempotent: stopping a stopped state is fine).
+ */
+export function cmdWuEnd(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const marker = activeWuMarkerPath(cwd);
+    if (existsSync(marker)) {
+        const prev = readFileSync(marker, "utf8").trim();
+        unlinkSync(marker);
+        return {
+            output: `nuos: cleared active work unit (was "${prev}")`,
+            exitCode: 0,
+        };
+    }
+    return {
+        output: "nuos: no active work unit to clear",
+        exitCode: 0,
+    };
+}
+/**
+ * `wu current` — print the current active WU handle or `(none)`.
+ * Always exits 0; absence is not an error.
+ */
+export function cmdWuCurrent(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const marker = activeWuMarkerPath(cwd);
+    if (existsSync(marker)) {
+        const handle = readFileSync(marker, "utf8").trim();
+        if (handle.length > 0) {
+            return { output: handle, exitCode: 0 };
+        }
+    }
+    return { output: "(none)", exitCode: 0 };
+}

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

@@ -15,13 +15,17 @@
  * @module setup/auto-index
  */
 /** Outcome of an auto-index attempt. */
-export type AutoIndexResult = {
-    kind: 'already_built';
-    indexPath: string;
-} | {
-    kind: 'just_built';
+export type AutoIndexResult = 
+/**
+ * The indexer ran. `indexed` includes both freshly-embedded files and
+ * re-embedded changed ones. `unchanged` is non-zero on subsequent
+ * runs — those files were SHA-matched and skipped without embedding.
+ */
+{
+    kind: 'ran';
     indexPath: string;
     indexed: number;
+    unchanged: number;
     chunks: number;
     durationMs: number;
 } | {
@@ -43,10 +47,11 @@ export interface AutoIndexOptions {
     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
+ * Run the indexer when conditions allow. Always runs (the indexer is
+ * incremental — unchanged files are SHA-skipped without embedding work),
+ * so this both *creates* the index on first call and *refreshes* it on
+ * subsequent calls. 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.

package/dist/setup/auto-index.js

@@ -19,10 +19,11 @@ import { resolveBuildRoot, resolveCatalogueRoot, resolveHashPath, resolveIndexPa
 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
+ * Run the indexer when conditions allow. Always runs (the indexer is
+ * incremental — unchanged files are SHA-skipped without embedding work),
+ * so this both *creates* the index on first call and *refreshes* it on
+ * subsequent calls. 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.
@@ -49,10 +50,13 @@ export async function ensureIndexBuilt(opts = {}) {
     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 };
-    }
+    // We do not short-circuit on `existsSync(indexPath)` — the indexer is
+    // already incremental via the per-file SHA hash store, so running it
+    // when the index is up-to-date is cheap (~1s on a 270-file catalogue
+    // with no changes). Short-circuiting here would leave newer files
+    // un-embedded until the user ran `nuos-catalogue index` manually,
+    // which is exactly the discoverability gap the auto-index is meant to
+    // close.
     // 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;
@@ -73,10 +77,17 @@ export async function ensureIndexBuilt(opts = {}) {
             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');
+    // LLM is ready. Run the indexer. The first run on a fresh project is
+    // ~30s of starter-kit content; subsequent runs are fast — the
+    // per-file SHA hashes mean unchanged files are skipped without
+    // embedding.
+    const isFirstRun = !existsSync(indexPath);
+    if (isFirstRun) {
+        out('Building search index for docs/build/ … (first run may take ~30 seconds)\n');
+    }
+    else {
+        out('Refreshing search index (incremental — only changed files are re-embedded)…\n');
+    }
     try {
         const { selectEmbedderFromEnv } = await import('../embedder/select.js');
         const { openStore } = await import('../store/open.js');
@@ -92,12 +103,23 @@ export async function ensureIndexBuilt(opts = {}) {
                 force: Boolean(opts.force),
                 dryRun: false,
             });
-            out(`✓ Indexed ${report.indexed} file(s), ${report.chunks} chunks embedded in ` +
-                `${(report.durationMs / 1000).toFixed(1)}s\n`);
+            const changed = report.indexed + report.updated;
+            const secs = (report.durationMs / 1000).toFixed(1);
+            if (isFirstRun) {
+                out(`✓ Indexed ${report.indexed} file(s), ${report.chunks} chunks embedded in ${secs}s\n`);
+            }
+            else if (changed === 0) {
+                out(`✓ Index up-to-date (${report.unchanged} files checked, none changed) in ${secs}s\n`);
+            }
+            else {
+                out(`✓ Re-indexed ${changed} changed file(s) (${report.unchanged} unchanged), ` +
+                    `${report.chunks} chunks embedded in ${secs}s\n`);
+            }
             return {
-                kind: 'just_built',
+                kind: 'ran',
                 indexPath,
-                indexed: report.indexed,
+                indexed: changed,
+                unchanged: report.unchanged,
                 chunks: report.chunks,
                 durationMs: report.durationMs,
             };
@@ -109,7 +131,7 @@ export async function ensureIndexBuilt(opts = {}) {
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        out(`\n✗ Index build failed: ${message}\n`);
+        out(`\n✗ Index refresh 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.20.0",
+  "version": "0.21.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": {
@@ -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 tests/wu-111-soak-findings.test.ts tests/plan.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",
+    "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/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",
     "typecheck": "tsc --noEmit",
     "index": "tsx src/cli.ts index",
     "search": "tsx src/cli.ts search"

package/templates/claude-hooks/check-implementation-write.sh

@@ -0,0 +1,167 @@
+#!/usr/bin/env bash
+#
+# NuOS Build Method — Claude Code PreToolUse hook (WU 136).
+#
+# Blocks Edit / Write / MultiEdit / NotebookEdit tool calls when:
+#   (a) the target file is OUTSIDE the catalogue project root, AND
+#   (b) no active work unit has been declared via `nuos-catalogue wu start <handle>`.
+#
+# Rationale
+# ─────────
+#   The existing git pre-commit hook (templates/hooks/pre-commit) catches
+#   catalogue-side drift on commit. It does not see writes to sibling
+#   implementation repos (sensight/, nuvector/, …) — those are different
+#   git roots. So an agent can ship hours of substantive implementation
+#   work across many sibling-repo files before any catalogue trace gets
+#   recorded. This hook closes that gap at the earliest possible moment:
+#   the file-write itself.
+#
+#   This is a soft-gate. The block is honest about what it is and how to
+#   release it (declare the active WU). The catalogue stays in charge of
+#   the project's discipline; the operator can override locally if a
+#   one-off write is genuinely needed (see "Manual override" below).
+#
+# Behaviour
+# ─────────
+#   1. Read the tool-call JSON on stdin (Claude Code PreToolUse contract).
+#   2. Extract `tool_input.file_path` or `tool_input.notebook_path`.
+#      If neither is present (parse failure), exit 0 — never block on
+#      ambiguous input.
+#   3. Determine the catalogue project root via $CLAUDE_PROJECT_DIR, falling
+#      back to `git rev-parse --show-toplevel` from cwd. If neither works,
+#      exit 0 (degrade-safe).
+#   4. Classify the target path:
+#        — Inside the project root: ALLOW. Editing the catalogue itself
+#          (work units, decisions, indexes, hooks, scripts) is the
+#          catalogue trace — no WU declaration required.
+#        — Outside the project root: this is sibling-repo implementation
+#          work and requires a declared active WU.
+#   5. For sibling-repo paths, check for an active-WU marker at
+#      `$PROJECT_ROOT/.nuos-catalogue/active-wu`.
+#        — Marker present (non-empty file): ALLOW. Log the touch with the
+#          declared WU handle so the audit trail names the work.
+#        — Marker absent or empty: BLOCK with exit 2 and a stderr message
+#          telling the operator what was blocked, what's missing, and the
+#          two commands to recover.
+#
+# Manual override
+# ───────────────
+#   If a write to a sibling repo is genuinely catalogue-orthogonal (e.g.
+#   adjusting a personal dotfile, applying a hotfix unrelated to project
+#   work), the operator can either:
+#     (a) declare a temporary "ad-hoc" WU: `nuos-catalogue wu start adhoc`
+#         then `nuos-catalogue wu end` when done. The audit log records
+#         the touches under "adhoc" — visible at end-of-session.
+#     (b) set NUOS_SKIP_IMPLEMENTATION_GATE=1 in the environment for that
+#         single tool call. The block is bypassed and a STRONG warning is
+#         emitted to stderr. The bypass is logged.
+#
+#   Bypass log lives at $PROJECT_ROOT/.nuos-enforcement.log alongside the
+#   catalogue-write hook's audit trail.
+#
+# Exit codes
+# ──────────
+#   0 — allow (or degrade-safe)
+#   2 — block (Claude Code surfaces stderr to the model)
+
+set -uo pipefail
+
+# ── Inputs ──────────────────────────────────────────────────────────────
+
+INPUT="$(cat 2>/dev/null || true)"
+
+# Project root: prefer the Claude-provided env var, fall back to git.
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-}"
+if [[ -z "$PROJECT_ROOT" ]]; then
+  PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+fi
+if [[ -z "$PROJECT_ROOT" ]]; then exit 0; fi
+
+LOG="$PROJECT_ROOT/.nuos-enforcement.log"
+
+# Extract the target file path. Edit/Write use `file_path`; NotebookEdit
+# uses `notebook_path`. MultiEdit also uses `file_path` (single root
+# file for the batch).
+FILE=$(printf '%s' "$INPUT" \
+  | grep -oE '"(file_path|notebook_path)"[[:space:]]*:[[:space:]]*"[^"]+"' \
+  | head -1 \
+  | sed -E 's/.*"([^"]+)"$/\1/')
+
+# Parse failure: degrade safe (never block on ambiguous input).
+if [[ -z "${FILE:-}" ]]; then exit 0; fi
+
+# ── Classify the target path ────────────────────────────────────────────
+
+# Normalise: if the path is relative, treat it as relative to cwd. The
+# tool always passes absolute paths in practice, but we guard regardless.
+case "$FILE" in
+  /*) ABSOLUTE_FILE="$FILE" ;;
+  *)  ABSOLUTE_FILE="$(pwd)/$FILE" ;;
+esac
+
+# Trailing-slash-tolerant prefix match.
+case "$ABSOLUTE_FILE/" in
+  "$PROJECT_ROOT"/*) IS_INTERNAL=1 ;;
+  *)                 IS_INTERNAL=0 ;;
+esac
+
+log_event() {
+  printf '%s | %s | %s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" "$1" "$2" >> "$LOG" 2>/dev/null || true
+}
+
+# ── Internal write: always allowed ──────────────────────────────────────
+
+if [[ "$IS_INTERNAL" == "1" ]]; then
+  exit 0
+fi
+
+# ── Sibling-repo write: requires an active WU declaration ──────────────
+
+# Manual override (escape hatch). Logged loudly.
+if [[ "${NUOS_SKIP_IMPLEMENTATION_GATE:-}" == "1" ]]; then
+  log_event "implementation-gate-bypassed" "$ABSOLUTE_FILE"
+  printf '⚠ nuos: NUOS_SKIP_IMPLEMENTATION_GATE=1 — sibling-repo write allowed without a WU declaration.\n' >&2
+  exit 0
+fi
+
+MARKER="$PROJECT_ROOT/.nuos-catalogue/active-wu"
+ACTIVE_WU=""
+if [[ -f "$MARKER" ]]; then
+  ACTIVE_WU="$(head -n 1 "$MARKER" 2>/dev/null | tr -d '[:space:]')"
+fi
+
+if [[ -n "$ACTIVE_WU" ]]; then
+  log_event "implementation-write-allowed[$ACTIVE_WU]" "$ABSOLUTE_FILE"
+  exit 0
+fi
+
+# Block. Stderr is surfaced to the model.
+log_event "implementation-write-blocked" "$ABSOLUTE_FILE"
+cat >&2 <<EOF
+✖ nuos: implementation write blocked (WU 136 gate).
+
+   Target file: $ABSOLUTE_FILE
+   Reason:      This path is OUTSIDE the catalogue project root
+                ($PROJECT_ROOT)
+                and no active work unit has been declared.
+
+   Substantive implementation work in a sibling repo must trace to a
+   catalogued work unit. Choose one of:
+
+     1. Declare an existing WU as active for this session:
+          nuos-catalogue wu start <handle>      e.g. wu start 136
+
+     2. File a new WU first, then declare it active:
+          nuos-catalogue wu create
+          nuos-catalogue wu start <new-handle>
+
+     3. When done, clear the marker:
+          nuos-catalogue wu end
+
+   Genuinely catalogue-orthogonal write? Set
+   NUOS_SKIP_IMPLEMENTATION_GATE=1 to bypass for one call (logged to
+   .nuos-enforcement.log for the audit trail).
+
+EOF
+
+exit 2