@nusoft/nuos-build-catalogue 0.20.1 → 0.22.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

@@ -51,7 +51,7 @@ const PROTOCOL_DESCRIPTIONS = {
     'end-of-session': 'Capture what happened, update state, write session log, commit',
     'wu-new': 'File a new work unit through a guided plain-English conversation',
     'persona-new': 'File a new persona by walking the seven dimensions conversationally',
-    'plan-orientation': 'Phase A of planning — project description, personas, the horizon map',
+    'plan-orientation': 'Phase A of planning — project description, tech stack, personas, the horizon map',
     'build-wu': 'Orchestrate a swarm of agents to build one work unit end-to-end',
 };
 const TOOLS = {

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/package.json

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

package/templates/protocols/build-wu.md

@@ -19,6 +19,7 @@ Also read:
 - The contracts it touches (`docs/build/contracts/`)
 - The architecture files for any modules involved (`docs/build/architecture/`)
 - The relevant design-system pieces if the work unit ships a UI surface
+- `methodfile.json`'s `techStack` section — if `techStack.defined` is `true`, extract the fields now; you'll inject them into every agent prompt in Step 4
 - Run `nuos-catalogue search "<work unit title or outcome>"` to find related prior work
 
 Before spawning any agents, search the cross-agent memory for relevant prior findings:
@@ -61,6 +62,20 @@ Skip steps when context allows — implementation-only WUs skip the architect; b
 
 Use Claude Code's **Task tool**. Each spawn names the agent (`subagent_type`), the model (from `methodfile.json`'s `swarm.models` block — usually leave as default), and the precise input.
 
+**Technical context injection:** If `techStack.defined` is `true` in `methodfile.json`, every agent spawn prompt must open with a "Technical context" block:
+
+```
+**Technical context (from methodfile.json):**
+- Languages: [languages]
+- Frontend: [frontend]
+- Backend: [backend]
+- Database: [database]
+- Deployment: [deployment]
+- External services: [externalServices]
+```
+
+Omit `null` fields. If `techStack.defined` is `false` or the section is absent, note it in the swarm audit entry and suggest the operator define the stack (`/plan-orientation` or edit `methodfile.json` directly) before the next swarm run — agents generating code without a known stack default to generic patterns that often need rework.
+
 **Spawn in parallel where possible.** If two agents can work independently (e.g. tester writing tests while reviewer reads design), spawn them in the same message. Sequential when an agent's output is the next agent's input (architect → coder).
 
 For each spawn:
@@ -141,7 +156,7 @@ Every decision made by any agent during the swarm MUST land in the catalogue bef
 
 ## Cost guidance
 
-A typical full-feature swarm spawning architect (Opus, ~30 min) + coder (Sonnet, ~1 hr) + tester (Sonnet, ~30 min) + reviewer (Sonnet, ~15 min) costs substantially less than running the same work as a continuous Opus conversation. Don't sweat exact figures — the 80/20 split is the lever. If a single work unit's swarm cost is becoming meaningful (>>£10), surface that to the operator before continuing; the WU is probably bigger than scoped.
+A typical full-feature swarm spawning architect (Opus, ~30 min) + coder (Sonnet, ~1 hr) + tester (Sonnet, ~30 min) + reviewer (Sonnet, ~15 min) consumes substantially less of the operator's coding-tool plan budget than running the same work as a continuous Opus conversation. The 80/20 split — heavy reasoning for design and debugging only, lighter models for implementation and verification — is the lever. If a single work unit's swarm is consuming an unusual share of the day's plan budget, surface that to the operator before continuing; the WU is probably bigger than scoped.
 
 ---
 
@@ -158,16 +173,6 @@ If the reviewer returns REQUEST CHANGES, re-spawn the coder ONCE to address the
 
 Don't loop indefinitely. A third reviewer rejection is a signal — the work unit's design, contract, or acceptance criteria need clarification, not more code.
 
-### Cost ceiling per work unit
-
-If the estimated cost (per the swarm audit) is exceeding **£10** for a single work unit:
-
-- STOP the swarm
-- Surface the cost trajectory to the operator
-- Recommend either splitting the work unit into smaller pieces, or accepting the higher cost with their explicit go-ahead
-
-This is a soft ceiling — the operator can authorise more. The point is to make cost visible before it accumulates invisibly.
-
 ### Time ceiling per agent
 
 If a single agent's run is taking substantially longer than its rough budget (architect >1 hr, coder >2 hrs, tester >1 hr, reviewer >30 min):

package/templates/protocols/plan-orientation.md

@@ -45,7 +45,43 @@ Listen. Don't interrupt. When they're done, summarise back in 2-3 sentences in y
 
 When the description is settled, **write it into `STATE.md`'s "What is currently in flight" section** — replacing the placeholder. Keep their voice; don't make it sound corporate. Show them the file path and confirm it's saved.
 
-## Step 3 — One persona, then one or two more (15-20 min)
+## Step 3 — Tech stack (5 min)
+
+Now ask what they're building it with:
+
+> "Before we meet the people your project is for — quickly, what are you building it with? Language, framework, database, where it'll run. If you know already, brilliant. If you haven't decided, just say so and we'll note it as an open question."
+
+Listen and capture what they give you. Common patterns:
+- *"Next.js, PostgreSQL, deployed on Vercel"* → frontend + database + deployment all filled
+- *"React Native with Firebase"* → frontend + database/backend filled
+- *"Not sure yet"* → set `defined: false`, file a Q-NNN
+
+**Write the result to `methodfile.json` now**, under the `techStack` section:
+
+```json
+{
+  "techStack": {
+    "defined": true,
+    "languages": ["TypeScript"],
+    "frontend": "Next.js 15 (App Router)",
+    "backend": "Next.js API Routes / Server Actions",
+    "database": "PostgreSQL (Supabase)",
+    "deployment": "Vercel",
+    "externalServices": ["Stripe"],
+    "notes": null
+  }
+}
+```
+
+Fill in what you know; set unknown fields to `null`. If nothing is settled, set `defined: false`, leave all fields null, and file a Q-NNN open question: *"Tech stack not yet decided — revisit before Phase B."*
+
+Show the operator the updated `methodfile.json` and confirm it saved. Tell them:
+
+> *"This means every agent we spawn later will know what it's building against — language, framework, where it runs. Just a few fields, but it prevents a lot of wrong output later."*
+
+**Drift discipline:** partial information is fine and still valuable. An operator who says *"definitely Next.js, not sure about the database yet"* should have `frontend: "Next.js"`, `database: null`, `defined: true`. Partial is better than undefined.
+
+## Step 4 — One persona, then one or two more (15-20 min)
 
 Tell the operator what's coming:
 
@@ -59,7 +95,7 @@ When P001 is filed, surface it and ask:
 
 If yes, run `/persona-new` again. Aim for **1-3 total** — more than 3 in Phase A usually means the project is overscoped; file the rest as open questions and revisit later.
 
-## Step 4 — Map 1: The Horizon (8-10 min)
+## Step 5 — Map 1: The Horizon (8-10 min)
 
 When the personas are filed, transition:
 
@@ -75,7 +111,7 @@ Use the template at `docs/build/maps/01-template.md`. Walk through its sections
 
 Write the map to `docs/build/maps/01-the-horizon.md`. Show them the file path and confirm.
 
-## Step 5 — Open questions (2 min)
+## Step 6 — Open questions (2 min)
 
 Pass over the conversation looking for anything the operator wasn't sure about. For each:
 
@@ -84,7 +120,7 @@ Pass over the conversation looking for anything the operator wasn't sure about.
 
 > "I noticed a few things you weren't sure about yet — [list]. I've filed them as open questions so we'll come back to them. Two of them affect Phase B (Architecture), so we'll definitely hit them next session."
 
-## Step 6 — Close (2 min)
+## Step 7 — Close (2 min)
 
 Update STATE.md:
 
@@ -96,6 +132,7 @@ Then tell the operator what they now have:
 
 > "You've got your first catalogue substrate:
 >
+> - **Tech stack** defined in `methodfile.json` — (or flagged as an open question if not yet settled)
 > - **[N] personas** in `docs/build/personas/` — these anchor every later decision
 > - **Map 1** at `docs/build/maps/01-the-horizon.md` — the whole-project picture
 > - **[N] open questions** in `docs/build/open-questions/` — these are what we'll resolve as planning continues

package/templates/protocols/wu-new.md

@@ -42,6 +42,8 @@ For infrastructure work, persona / trigger / walkthrough are marked `N/A — inf
 
 ## Step 4 — File the work unit
 
+Before writing the file, check `methodfile.json`'s `techStack.defined`. If it's `false` or the field is absent, tell the operator: *"I notice the tech stack isn't defined yet — that normally happens during Phase A planning. Want to define it now, or shall I file an open question?"* Either way, continue filing the work unit. If `defined` is `true`, the acceptance criteria may reference the stack where relevant (e.g. *"renders correctly with Next.js App Router SSR"*).
+
 1. **Number it.** Scan `docs/build/work-units/` and `docs/build/work-units/done/` for the highest existing 3-digit prefix; new number is max + 1.
 2. **Slugify the title.** Lowercase; dashes for spaces; no special characters; cap at 60 chars.
 3. **Write the file** at `docs/build/work-units/NNN-slug.md`. Use `001-template-simple.md` for the simple shape, `001-template-full.md` for the full shape.

package/templates/starter-kit/methodfile.json

@@ -9,6 +9,16 @@
     "tagline": "{{PROJECT_TAGLINE}}",
     "domain": "{{PROJECT_DOMAIN}}"
   },
+  "techStack": {
+    "defined": false,
+    "languages": [],
+    "frontend": null,
+    "backend": null,
+    "database": null,
+    "deployment": null,
+    "externalServices": [],
+    "notes": null
+  },
   "catalogue": {
     "root": "docs/build/",
     "registers": {