@nusoft/nuos-build-catalogue 0.30.3 → 0.32.0

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

@@ -1,11 +1,15 @@
 /**
- * `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.
+ * `install-hooks` — copy every Claude Code PreToolUse hook shipped in
+ * the package into the consumer's `.claude/hooks/`, wire them into the
+ * consumer's `.claude/settings.json` under a single shared matcher,
+ * and add the active-WU marker file to `.gitignore`.
  *
- * Idempotent. Safe to re-run after package upgrades — the hook script
- * is overwritten, the settings entry is added only if missing, and the
+ * Hooks discovered automatically by scanning `templates/claude-hooks/`
+ * for `*.sh` files — adding a new hook to that directory is enough to
+ * have it installed on the next consumer upgrade.
+ *
+ * Idempotent. Safe to re-run after package upgrades — hook scripts
+ * are overwritten, settings entries are added only if missing, and the
  * gitignore line is appended only if not present.
  *
  * @module commands/install-claude-hooks
@@ -20,10 +24,21 @@ export interface InstallClaudeHooksOptions {
     templatesDir?: string;
 }
 /**
- * Idempotently install the Claude PreToolUse hook into the project at
+ * Idempotently install every Claude PreToolUse hook into the project at
  * `cwd`. Returns a CommandResult describing what was done.
  */
 export declare function cmdInstallClaudeHooks(opts?: InstallClaudeHooksOptions): CommandResult;
+/**
+ * Add a `{type:"command", command}` hook entry under the PreToolUse
+ * matcher. If a matcher entry with the same `matcher` string already
+ * exists, the command is appended to its `hooks` array (deduped by
+ * command string). Otherwise a new matcher entry is created. Settings
+ * that already contain the command anywhere under PreToolUse are
+ * returned unchanged.
+ *
+ * Pure function: takes settings in, returns a new settings object plus
+ * a `changed` flag indicating whether anything was actually added.
+ */
 export declare function addPreToolUseHook(settings: Record<string, unknown>, matcher: string, command: string): {
     value: Record<string, unknown>;
     changed: boolean;

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

@@ -1,21 +1,27 @@
 /**
- * `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.
+ * `install-hooks` — copy every Claude Code PreToolUse hook shipped in
+ * the package into the consumer's `.claude/hooks/`, wire them into the
+ * consumer's `.claude/settings.json` under a single shared matcher,
+ * and add the active-WU marker file to `.gitignore`.
  *
- * Idempotent. Safe to re-run after package upgrades — the hook script
- * is overwritten, the settings entry is added only if missing, and the
+ * Hooks discovered automatically by scanning `templates/claude-hooks/`
+ * for `*.sh` files — adding a new hook to that directory is enough to
+ * have it installed on the next consumer upgrade.
+ *
+ * Idempotent. Safe to re-run after package upgrades — hook scripts
+ * are overwritten, settings entries are 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 { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, 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}`;
+// The active-WU marker is read only by check-implementation-write.sh.
+// We add it to .gitignore whenever that hook is being installed.
+const IMPLEMENTATION_HOOK = "check-implementation-write.sh";
+const ACTIVE_WU_MARKER = ".nuos-catalogue/active-wu";
 /**
  * Resolve the path to the bundled `templates/claude-hooks/` directory.
  * When running from `dist/` (the published package) the templates dir
@@ -25,8 +31,6 @@ const SETTINGS_COMMAND = `bash .claude/hooks/${HOOK_FILENAME}`;
  */
 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"),
@@ -35,61 +39,77 @@ function resolveTemplatesDir() {
         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
+ * Idempotently install every 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)) {
+    if (!existsSync(templatesDir)) {
+        return {
+            output: `✖ nuos: hook templates directory not found at ${templatesDir}\n   The package may be installed incorrectly. Try reinstalling.`,
+            exitCode: 1,
+        };
+    }
+    const hookFiles = readdirSync(templatesDir)
+        .filter((f) => f.endsWith(".sh"))
+        .sort();
+    if (hookFiles.length === 0) {
         return {
-            output: `✖ nuos: hook template not found at ${srcHook}\n   The package may be installed incorrectly. Try reinstalling.`,
+            output: `✖ nuos: no hook scripts found in ${templatesDir}`,
             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.
+    // 1. Copy every hook script into .claude/hooks/.
+    for (const filename of hookFiles) {
+        const src = join(templatesDir, filename);
+        const dest = join(hooksDir, filename);
+        copyFileSync(src, dest);
+        try {
+            chmodSync(dest, 0o755);
+        }
+        catch {
+            // chmod is best-effort on filesystems that don't support it.
+        }
+        lines.push(`  ✓ installed hook → .claude/hooks/${filename}`);
     }
-    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.
+    // 2. Merge into .claude/settings.json. All hooks share one PreToolUse
+    //    matcher; each contributes one command entry.
     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");
+    let settings = readJsonOrEmpty(settingsPath);
+    let settingsChanged = false;
+    for (const filename of hookFiles) {
+        const command = `bash .claude/hooks/${filename}`;
+        const updated = addPreToolUseHook(settings, SETTINGS_MATCHER, command);
+        settings = updated.value;
+        if (updated.changed)
+            settingsChanged = true;
     }
-    // 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");
+    if (settingsChanged) {
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+        lines.push("  ✓ updated .claude/settings.json (PreToolUse entries added)");
     }
     else {
-        lines.push("  · .nuos-catalogue/active-wu already in .gitignore");
+        lines.push("  · .claude/settings.json already has every PreToolUse entry");
+    }
+    // 3. Add the active-WU marker to .gitignore — only relevant when the
+    //    implementation-write hook is part of the bundle.
+    if (hookFiles.includes(IMPLEMENTATION_HOOK)) {
+        const gitignorePath = join(cwd, ".gitignore");
+        const added = ensureGitignoreEntry(gitignorePath, ACTIVE_WU_MARKER);
+        if (added) {
+            lines.push(`  ✓ added ${ACTIVE_WU_MARKER} to .gitignore`);
+        }
+        else {
+            lines.push(`  · ${ACTIVE_WU_MARKER} already in .gitignore`);
+        }
     }
     return {
         output: [
@@ -113,12 +133,22 @@ function readJsonOrEmpty(path) {
         return {};
     }
 }
+/**
+ * Add a `{type:"command", command}` hook entry under the PreToolUse
+ * matcher. If a matcher entry with the same `matcher` string already
+ * exists, the command is appended to its `hooks` array (deduped by
+ * command string). Otherwise a new matcher entry is created. Settings
+ * that already contain the command anywhere under PreToolUse are
+ * returned unchanged.
+ *
+ * Pure function: takes settings in, returns a new settings object plus
+ * a `changed` flag indicating whether anything was actually added.
+ */
 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).
+    // Already present anywhere? Dedupe by command string.
     for (const entry of preToolUse) {
         for (const h of entry.hooks ?? []) {
             if (h.command === command) {
@@ -126,11 +156,29 @@ export function addPreToolUseHook(settings, matcher, command) {
             }
         }
     }
-    const newEntry = {
-        matcher,
-        hooks: [{ type: "command", command }],
-    };
-    const newPreToolUse = [...preToolUse, newEntry];
+    // Look for an existing matcher with the same matcher string and
+    // append to it — keeps all our hooks under a single matcher entry,
+    // matching the shape the catalogue uses in its own settings.json.
+    const matchingIndex = preToolUse.findIndex((e) => e.matcher === matcher);
+    let newPreToolUse;
+    if (matchingIndex >= 0) {
+        const existing = preToolUse[matchingIndex];
+        const merged = {
+            matcher: existing.matcher,
+            hooks: [...(existing.hooks ?? []), { type: "command", command }],
+        };
+        newPreToolUse = [
+            ...preToolUse.slice(0, matchingIndex),
+            merged,
+            ...preToolUse.slice(matchingIndex + 1),
+        ];
+    }
+    else {
+        newPreToolUse = [
+            ...preToolUse,
+            { matcher, hooks: [{ type: "command", command }] },
+        ];
+    }
     const newHooks = { ...hooksField, PreToolUse: newPreToolUse };
     next.hooks = newHooks;
     return { value: next, changed: true };
@@ -143,7 +191,9 @@ export function ensureGitignoreEntry(path, line) {
     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";
+    const newBody = body.endsWith("\n") || body.length === 0
+        ? body + line + "\n"
+        : body + "\n" + line + "\n";
     writeFileSync(path, newBody, "utf8");
     return true;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nusoft/nuos-build-catalogue",
-  "version": "0.30.3",
+  "version": "0.32.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/templates/agents/architect.md

@@ -59,6 +59,48 @@ When you're done, write a brief to the coder agent in the work unit's notes —
 
 If you find yourself writing *"likely"*, *"presumably"*, *"should work"* in your decision, that's a missing verification step. Replace it with a concrete check, or file the uncertainty as an open question. Hedge words leave room for plausible-looking work that doesn't match reality.
 
+## Module discipline — deep, not shallow
+
+**Every design you produce sits inside the project's module structure. The structure is built from deep modules — small interface, large hidden complexity — and never from shallow ones.** This is the single most load-bearing architectural commitment in the project. Read `docs/philosophy/deep-modules.md` before your first design pass on any new project, and re-read it whenever you find yourself reaching for a new module.
+
+### Before you design
+
+Read the WU's `Module:` field. Read the architecture file for that module. Your design extends that module's hidden complexity — its `Interface surface` should grow as little as possible, its `Hidden complexity` should grow to absorb the new work.
+
+### When the WU proposes a new module
+
+If the `/wu-new` intake gate routed a new-module proposal to you, you produce the architecture file *before* the WU is filed. Use `docs/build/architecture/module-template.md`. Every field is required — especially:
+
+- **Interface surface** — list every public entry point. Few. Named. Stable.
+- **Hidden complexity** — list every piece of state, branching, integration, edge case the module absorbs. Many. Specific.
+- **Depth justification** — two or three sentences answering: *why is the hidden body genuinely larger than the interface?* If you can't answer this, the module is shallow — fold the work into an existing module instead.
+- **Paths claimed** — every source path this module owns. The `check-module-discipline.sh` hook reads this to block writes to unclaimed paths.
+
+### Shallow-module patterns you must not propose
+
+The build-wu deep-module gate will reject any of these. Catch them yourself first:
+
+- **The pass-through wrapper** — public methods each call exactly one method in another module. Adds interface cost without encapsulation.
+- **The util / helper / shared / common / lib / misc grab-bag** — these names are banned. The work lives inside the module whose hidden complexity needs it.
+- **The thin adapter** — renames or thinly re-exports another module. Rename at the source instead.
+- **The micro-module** — three files, four functions, no significant hidden body. Merge into the deepest reasonable existing module.
+- **The premature split** — splitting one coherent responsibility into two modules to "separate concerns" when those concerns are not separable in the runtime. One deep module beats two shallow ones.
+- **The interface-equals-body module** — `Interface surface` items roughly equal `Hidden complexity` items. The depth ratio is ~1; the module has no depth.
+
+### When in doubt, fold into an existing module
+
+Default to **extend an existing deep module**. Only propose a new module when:
+
+1. No existing module's `Hidden complexity` can plausibly absorb the responsibility, AND
+2. The new module's hidden body is *much larger* than its interface, AND
+3. You can write a depth justification you would defend in review.
+
+The cost of an under-split module is rework (cheap; you can split later). The cost of an over-split system is permanent shallow sprawl (expensive; nobody ever un-splits). When the call is close, fold in.
+
+### Make module-depth one of your design-it-twice axes
+
+When you produce two structurally different designs (Pattern N), make **module-depth shape** one of the structural axes whenever the work has any module-boundary implications. Example: *Design A folds the new behaviour into the existing `consolidation` module (interface grows by 1 method, hidden body absorbs the new state machine). Design B creates a new `consolidation-replay` module (interface = 4 methods, hidden body = the replay engine + scheduling).* Then pick on depth, cohesion, and the cost-of-being-wrong asymmetry above — not on "which feels neater."
+
 ## No shortcuts. No workarounds. No provisional designs.
 
 **This is absolute.** The architect's job is to produce the correct, fully-designed solution — not the fastest one, not the simplest one, not the one that fits inside this sprint. Speed of delivery is never a valid input to an architectural decision.

package/templates/claude-hooks/check-module-discipline.sh

@@ -0,0 +1,355 @@
+#!/usr/bin/env bash
+#
+# NuOS Build Method — Deep-Module Discipline Hook (PreToolUse)
+#
+# Blocks Write / Edit / MultiEdit / NotebookEdit when:
+#   (a) the target file is a source file under a recognised source tree,
+#       AND
+#   (b) the catalogue has an architecture register at
+#       docs/build/architecture/ with at least one module filed, AND
+#   (c) the target path is NOT claimed by any module's `## Paths claimed`
+#       block.
+#
+# Rationale
+# ─────────
+#   The catalogue's value over a long build depends on the project staying
+#   built from DEEP modules — small interface, large hidden body. The most
+#   reliable failure mode is an agent quietly creating a shallow module
+#   mid-implementation: a new `src/foo/` directory, a `utils.ts`, a thin
+#   wrapper "to keep things tidy." Once written, these are permanent —
+#   every later WU builds against them and un-splitting them is too costly
+#   to ever happen.
+#
+#   The /wu-new intake gate and the /build-wu architectural quality gate
+#   are the conversational defences. This hook is the mechanical one. It
+#   reads the architecture register to learn which source paths are
+#   claimed by which module, and blocks any write to an unclaimed source
+#   path. The agent's only recovery path is to (a) extend the relevant
+#   module's `Paths claimed`, or (b) propose a new module via the
+#   architect (which itself must justify depth before it can claim paths).
+#
+#   Doctrine: docs/philosophy/deep-modules.md
+#
+# Degrade-safe behaviour
+# ──────────────────────
+#   The hook exits 0 (allow) without enforcement when:
+#     • CLAUDE_PROJECT_DIR is unset and no git root is detectable
+#     • the architecture register does not exist
+#     • the architecture register exists but contains no module files
+#       (only _index.md / module-template.md — project is pre-architecture)
+#     • the target file is not a source file (configs, docs, scripts, tests)
+#     • the target file lives inside the catalogue itself
+#     • the JSON tool input cannot be parsed
+#     • jq and python3 are both unavailable
+#
+#   "Better to wave a violation through than to block a legitimate write
+#   the operator did not anticipate" — the conversational gates catch
+#   most things; this hook is the safety net, not the only defence.
+#
+# Override
+# ────────
+#   Set NUOS_SKIP_MODULE_DISCIPLINE=1 in the environment for one tool call
+#   to bypass. Logged to .nuos-enforcement.log for the audit trail.
+#
+# Exit codes
+# ──────────
+#   0 — allow (or degrade-safe)
+#   2 — block (Claude Code surfaces stderr to the model)
+
+set -uo pipefail
+
+INPUT="$(cat 2>/dev/null || true)"
+
+# ── Project root ──────────────────────────────────────────────────────────────
+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"
+
+log_event() {
+  printf '%s | %s | %s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" "$1" "$2" >> "$LOG" 2>/dev/null || true
+}
+
+# ── Override ──────────────────────────────────────────────────────────────────
+if [[ "${NUOS_SKIP_MODULE_DISCIPLINE:-}" == "1" ]]; then
+  log_event "module-discipline-bypassed" "${PWD}"
+  printf '⚠ nuos: NUOS_SKIP_MODULE_DISCIPLINE=1 — module-discipline check skipped.\n' >&2
+  exit 0
+fi
+
+# ── Extract file path ─────────────────────────────────────────────────────────
+FILE=$(printf '%s' "$INPUT" \
+  | grep -oE '"(file_path|notebook_path)"[[:space:]]*:[[:space:]]*"[^"]+"' \
+  | head -1 \
+  | sed -E 's/"(file_path|notebook_path)"[[:space:]]*:[[:space:]]*"//' \
+  | tr -d '"')
+
+if [[ -z "${FILE:-}" ]]; then exit 0; fi
+
+# Normalise to absolute
+case "$FILE" in
+  /*) ABSOLUTE_FILE="$FILE" ;;
+  *)  ABSOLUTE_FILE="$(pwd)/$FILE" ;;
+esac
+
+# ── Skip the catalogue itself ─────────────────────────────────────────────────
+# Writes inside docs/build/, docs/philosophy/, docs/guides/, docs/contracts/,
+# .claude/, .agents/, .opencode/, templates/, scripts/ etc. are catalogue
+# work — never module-implementation work.
+case "$ABSOLUTE_FILE" in
+  */docs/*|*/.claude/*|*/.agents/*|*/.opencode/*|*/.nuos-catalogue/*|*/CLAUDE.md|*/README.md|*/CHANGELOG.md)
+    exit 0 ;;
+esac
+
+# Skip common non-source paths
+case "$ABSOLUTE_FILE" in
+  */node_modules/*|*/dist/*|*/.next/*|*/build/*|*/.nuxt/*|*/coverage/*|*/.git/*|*/.turbo/*|*/.vercel/*)
+    exit 0 ;;
+  */tests/*|*/test/*|*/__tests__/*|*/e2e/*|*/spec/*|*/__mocks__/*|*/fixtures/*)
+    exit 0 ;;
+  */scripts/*|*/bin/*|*/migrations/*|*/seed/*|*/seeds/*)
+    exit 0 ;;
+  */public/*|*/static/*|*/assets/*)
+    exit 0 ;;
+esac
+
+# Skip non-source file types
+case "$ABSOLUTE_FILE" in
+  *.test.ts|*.test.tsx|*.test.js|*.test.jsx|*.test.mjs|*.test.cjs)
+    exit 0 ;;
+  *.spec.ts|*.spec.tsx|*.spec.js|*.spec.jsx|*.spec.mjs|*.spec.cjs)
+    exit 0 ;;
+  *.d.ts|*.config.ts|*.config.js|*.config.mjs|*.config.cjs)
+    exit 0 ;;
+  *.json|*.yaml|*.yml|*.toml|*.ini|*.env|*.md|*.txt|*.lock|*.sum|*.mod)
+    exit 0 ;;
+  *.png|*.jpg|*.jpeg|*.gif|*.svg|*.ico|*.webp|*.avif|*.woff|*.woff2|*.ttf|*.otf|*.eot)
+    exit 0 ;;
+  *.sh|*.bash|*.zsh|*.fish|*.ps1|*.bat|*.cmd)
+    exit 0 ;;
+  *.lock|*Dockerfile*|*.dockerignore|*.gitignore|*.gitattributes|*.npmignore)
+    exit 0 ;;
+esac
+
+# Only enforce on these source extensions
+EXTENSION="${ABSOLUTE_FILE##*.}"
+case "$EXTENSION" in
+  ts|tsx|js|jsx|mjs|cjs|py|rb|go|rs|java|kt|swift|cs|c|cpp|cc|h|hpp|php|ex|exs|erl|hs|ml|scala|clj|elm) : ;;
+  vue|svelte|astro) : ;;
+  *) exit 0 ;;
+esac
+
+# ── Find the architecture register ────────────────────────────────────────────
+ARCH_DIR=""
+if [[ -d "$PROJECT_ROOT/docs/build/architecture" ]]; then
+  ARCH_DIR="$PROJECT_ROOT/docs/build/architecture"
+else
+  # Split-repo pattern: look for a sibling catalogue
+  PARENT="$(dirname "$PROJECT_ROOT")"
+  for sibling in "$PARENT"/*/docs/build/architecture; do
+    if [[ -d "$sibling" ]]; then
+      ARCH_DIR="$sibling"
+      break
+    fi
+  done
+fi
+
+# No architecture register → project is pre-architecture; degrade-safe.
+if [[ -z "$ARCH_DIR" ]]; then exit 0; fi
+
+# Collect module files (everything except _index.md and module-template.md).
+shopt -s nullglob
+MODULE_FILES=()
+for f in "$ARCH_DIR"/*.md; do
+  base="$(basename "$f")"
+  case "$base" in
+    _index.md|module-template.md) continue ;;
+  esac
+  MODULE_FILES+=("$f")
+done
+shopt -u nullglob
+
+# No modules filed yet → degrade-safe.
+if [[ ${#MODULE_FILES[@]} -eq 0 ]]; then exit 0; fi
+
+# ── Compute the target's path relative to its repo root ───────────────────────
+# In-repo case: relative to PROJECT_ROOT.
+# Sibling-repo case: relative to the sibling's git toplevel.
+TARGET_REPO_ROOT=""
+case "$ABSOLUTE_FILE/" in
+  "$PROJECT_ROOT"/*)
+    TARGET_REPO_ROOT="$PROJECT_ROOT" ;;
+  *)
+    # Resolve the sibling repo root by asking git from the file's directory.
+    TARGET_DIR="$(dirname "$ABSOLUTE_FILE")"
+    if [[ -d "$TARGET_DIR" ]]; then
+      TARGET_REPO_ROOT="$(git -C "$TARGET_DIR" rev-parse --show-toplevel 2>/dev/null || true)"
+    fi
+    ;;
+esac
+
+# Couldn't resolve a repo root for the target → degrade-safe.
+if [[ -z "$TARGET_REPO_ROOT" ]]; then exit 0; fi
+
+# Strip the repo root prefix → relative path.
+RELATIVE_TARGET="${ABSOLUTE_FILE#$TARGET_REPO_ROOT/}"
+
+# If stripping didn't change anything, we couldn't compute a relative path.
+if [[ "$RELATIVE_TARGET" == "$ABSOLUTE_FILE" ]]; then exit 0; fi
+
+# Repo-root-level files (no directory) are never source modules.
+case "$RELATIVE_TARGET" in
+  */*) : ;;
+  *) exit 0 ;;
+esac
+
+# ── Extract all claimed paths from every module file ──────────────────────────
+# A module file's "Paths claimed" section looks like:
+#
+#   ## Paths claimed
+#
+#   > *Required. List the source-tree paths...*
+#
+#   - `src/auth/`
+#   - `apps/web/src/auth/**`
+#
+# We collect every bullet-list entry under that heading, stripping
+# backticks, quotes, and trailing glob/slash suffixes to derive a prefix
+# we can match against.
+
+extract_claims() {
+  local file="$1"
+  awk '
+    BEGIN { in_section = 0 }
+    /^## Paths claimed/ { in_section = 1; next }
+    /^## / && in_section { in_section = 0 }
+    in_section {
+      # bullet line: leading - or * followed by content
+      if (match($0, /^[[:space:]]*[-*][[:space:]]+/)) {
+        line = substr($0, RSTART + RLENGTH)
+        # strip blockquote markers / italics that may leak from template hints
+        gsub(/^[[:space:]]*\*[[:space:]]*/, "", line)
+        # take only the first backticked token if present, else first whitespace-free token
+        if (match(line, /`[^`]+`/)) {
+          token = substr(line, RSTART + 1, RLENGTH - 2)
+        } else {
+          # first whitespace-delimited token
+          n = split(line, parts, /[[:space:]]+/)
+          token = parts[1]
+        }
+        # ignore template placeholders like [module-slug]
+        if (token ~ /^\[/) next
+        if (token == "") next
+        print token
+      }
+    }
+  ' "$file"
+}
+
+CLAIMS=()
+CLAIM_OWNERS=()  # parallel array: which module file each claim came from
+for mf in "${MODULE_FILES[@]}"; do
+  while IFS= read -r claim; do
+    [[ -z "$claim" ]] && continue
+    CLAIMS+=("$claim")
+    CLAIM_OWNERS+=("$(basename "$mf" .md)")
+  done < <(extract_claims "$mf")
+done
+
+# No claims declared anywhere → degrade-safe (modules exist but none have
+# populated Paths claimed yet — treat as still bootstrapping).
+if [[ ${#CLAIMS[@]} -eq 0 ]]; then exit 0; fi
+
+# ── Match target against claims ──────────────────────────────────────────────
+# Normalise a claim into a prefix: strip leading `./`, trailing `/**`,
+# `/*`, or `/`. Match if RELATIVE_TARGET starts with the prefix followed
+# by `/` or equals the prefix exactly.
+
+normalise_claim() {
+  local c="$1"
+  c="${c#./}"
+  c="${c%/}"
+  c="${c%/\*\*}"
+  c="${c%/\*}"
+  printf '%s' "$c"
+}
+
+MATCHED=0
+for claim in "${CLAIMS[@]}"; do
+  prefix="$(normalise_claim "$claim")"
+  [[ -z "$prefix" ]] && continue
+  if [[ "$RELATIVE_TARGET" == "$prefix" || "$RELATIVE_TARGET" == "$prefix"/* ]]; then
+    MATCHED=1
+    break
+  fi
+done
+
+if [[ "$MATCHED" == "1" ]]; then
+  exit 0
+fi
+
+# ── Block ─────────────────────────────────────────────────────────────────────
+log_event "module-discipline-blocked" "$ABSOLUTE_FILE"
+
+# Build the "available modules" summary for the error message.
+MODULE_SUMMARY=""
+for mf in "${MODULE_FILES[@]}"; do
+  slug="$(basename "$mf" .md)"
+  # Pull the first non-blank line under "## What this module does".
+  desc=$(awk '
+    BEGIN { in_section = 0; printed = 0 }
+    /^## What this module does/ { in_section = 1; next }
+    /^## / && in_section { exit }
+    in_section && printed == 0 && NF > 0 && $0 !~ /^>/ {
+      print
+      printed = 1
+      exit
+    }
+  ' "$mf" 2>/dev/null | head -c 140)
+  MODULE_SUMMARY+="
+     • $slug — ${desc:-(no summary)}"
+done
+
+cat >&2 <<EOF
+✖ nuos: deep-module discipline block — unclaimed source path.
+
+   Target file:   $RELATIVE_TARGET
+   (resolved to:  $ABSOLUTE_FILE)
+
+   This path is not claimed by any module in
+   $ARCH_DIR
+
+   The doctrine: every source file lives inside a deep module that
+   explicitly claims it under '## Paths claimed' in its architecture
+   file. New unclaimed source paths are the failure mode that creates
+   shallow modules (util grab-bags, pass-through wrappers, premature
+   splits). See docs/philosophy/deep-modules.md.
+
+   Modules currently filed:$MODULE_SUMMARY
+
+   ── Required action ──────────────────────────────────────────────────────────
+
+   Pick one:
+
+     1. The work belongs in an EXISTING module above. Open that
+        module's architecture file and add the path under
+        '## Paths claimed', then retry the write.
+
+     2. The work is genuinely a NEW deep module. STOP this write.
+        Run the architect to propose the module (interface surface,
+        hidden complexity, depth justification, paths claimed),
+        file docs/build/architecture/<slug>.md from
+        module-template.md, THEN retry.
+
+   Never: invent a name like 'utils', 'helpers', 'common', 'shared',
+   'lib', or 'misc' to bypass this gate — those are shallow-module
+   patterns and will be rejected by the architectural quality gate.
+
+   Override (logged): NUOS_SKIP_MODULE_DISCIPLINE=1 for one call.
+
+EOF
+
+exit 2

package/templates/protocols/build-wu.md

@@ -37,6 +37,14 @@ nuos-catalogue memory search --query="<the module or contract name being worked
 
 Surface any high-score memories (> 0.8) to the relevant agents as additional context in their spawn prompt. Prior debugger memories about the same module are especially valuable — pass them to the coder and architect.
 
+## Step 1.5 — Load the owning module (mandatory)
+
+The WU must have a `Module:` field set (added by the `/wu-new` deep-module intake gate). Read it.
+
+- **If the field is set**, read `docs/build/architecture/<module-slug>.md` in full — especially `Interface surface`, `Hidden complexity`, and `Paths claimed`. Every agent spawned for this WU must receive the architecture file as required reading in their spawn prompt. The coder must not touch any source path that is not listed in the module's `Paths claimed` block (the `check-module-discipline.sh` PreToolUse hook will block them otherwise).
+
+- **If the field is missing** (legacy WUs filed before the intake gate, or a hand-filed WU that skipped the gate), STOP. Tell the operator: *"This WU has no module assigned. The deep-module discipline requires every WU to declare which module it lives in. Want me to walk through the intake gate now — pick from existing modules or have the architect propose a new one — before the swarm proceeds?"* Do not classify or spawn anything until `Module:` is set and the architecture file is read.
+
 ## Step 2 — Classify the work
 
 Decide what shape this work is. Most work units fall into one of these patterns:
@@ -182,6 +190,20 @@ If `methodfile.json` has `e2e.enabled: true`, run the Playwright test suite from
 
 If `methodfile.json` has no `e2e` section or `e2e.enabled: false`, skip this gate but note in the audit entry: *"Playwright gate skipped — e2e not configured in methodfile.json"*. For UI-surfacing work units (any WU that adds or changes a page, component, or user interaction), prompt the developer: *"This WU ships a UI change but no Playwright spec exists. Want me to file a follow-up WU to add e2e coverage for this surface?"*
 
+## Step 5.7 — Code-quality lite gate (only if the coder touched source)
+
+Runs after the test gates pass, before promotion. Pure self-check by the coordinator on the coder's staged diff. Skip entirely if the WU was design-only or only touched docs/registers.
+
+Against `git diff --name-only <base>...HEAD` filtered to source files (same filter as Step 5.5 Gate B), scan for these three lite-gate items only:
+
+1. **1k-line cross** — did this WU push any file from under 1000 lines to over 1000 lines? If yes, surface to the operator: *"WU N pushed [file] from X → Y lines. Decompose before promotion, or accept the sprawl?"* Don't auto-decompose; this is an operator call.
+2. **Spaghetti** — does the diff add ad-hoc conditionals, one-off booleans, or special-case branches bolted into unrelated flows? If yes, send back to the coder with: *"This adds a special-case branch into [flow]. Move it behind its own abstraction before promotion."*
+3. **Canonical-helper duplication** — does the diff introduce a bespoke helper that duplicates an existing utility the codebase already has? If yes, send back to the coder with the path to the canonical helper.
+
+These are the three highest-yield checks from the full thermo-nuclear code-quality rubric. The full rubric runs at end-of-session against the staged commit diff (see [end-of-session.md](end-of-session.md) Step 10) and escalates to `/thermo-nuclear-code-quality-review` for the harsh pass. The lite gate here is the cheap-early-warning so structural mistakes are caught before they layer with downstream agent output.
+
+Record `✓ code-quality lite gate passed` (or the trigger if it fired) in the swarm audit entry under `## Gate triggers`.
+
 ## Step 6 — Record the swarm run
 
 Write an audit entry at `docs/build/swarm/YYYY-MM-DD-wu-<handle>.md`. Use the template at `docs/build/swarm/_template.md`. Capture:
@@ -272,6 +294,29 @@ Before routing the architect's brief to the coder, read it for shortcut indicato
 
 Do not feel time or cost pressure. A proper design that takes longer is always preferred over a shortcut that ships sooner. Routing a shortcut brief to the coder does not save time — it produces code the reviewer will block, and the loop costs more than getting the design right once.
 
+### Deep-module gate (after architect, before coder — mandatory)
+
+Runs alongside the architectural quality gate above. Reads the architect's brief specifically for module-depth violations. Doctrine: [docs/philosophy/deep-modules.md](../../starter-kit/docs/philosophy/deep-modules.md). This is also a **hard stop**.
+
+**Before checking, confirm the WU has a `Module:` field set.** If the WU was filed without one (legacy WUs from before the intake gate, or a hand-filed WU that skipped `/wu-new`), STOP and route to the operator: *"This WU has no module assigned. Run the deep-module intake gate before the swarm can spawn — either pick an existing module from `docs/build/architecture/`, or have the architect propose a new one."* Do not let the swarm proceed without `Module:` set.
+
+**Shallow-module red flags in the architect's brief — any one is a rejection:**
+
+- **A new module is being proposed without its architecture file already filed.** The architect must produce `docs/build/architecture/<slug>.md` (using `module-template.md`) before the coder spawns. The file must have every field populated — including `Interface surface`, `Hidden complexity`, `Depth justification`, and `Paths claimed`. A brief that says "we'll file the architecture entry after coding" is a rejection.
+- **A new module whose `Interface surface` is roughly as wide as its `Hidden complexity`.** Count the items; if interface ≥ hidden, the module is shallow. Reject and tell the architect: *"This module's interface is not narrower than its body — it has no depth. Either fold this work into an existing module whose hidden complexity it actually serves, or expand the hidden body to justify the boundary."*
+- **A new module named `utils`, `helpers`, `common`, `shared`, `lib`, `misc`, or any variant.** These names signal grab-bags by construction. Reject. Tell the architect: *"This project has no utils module by design. The work this names must live inside the module whose hidden complexity needs it. Which module is that?"*
+- **A new module that is a pass-through wrapper** — its public methods each call exactly one method in another module. Reject; the wrapping module adds interface cost without adding encapsulation.
+- **A new module that re-exports or thinly adapts another module.** Reject; rename or adapt at the existing module instead.
+- **A design that splits one coherent responsibility across two new modules** to "separate concerns" when those concerns are not actually separable in the runtime. Reject; one deep module is better than two shallow ones.
+- **The brief touches source paths not claimed by any module's `## Paths claimed` section.** Reject; either update the owning module's claimed paths in the brief, or run the new-module flow first.
+- **The architect's brief proposes a new module when an existing module's `Hidden complexity` plausibly covers the responsibility.** Reject and ask the architect to either (a) demonstrate the responsibility does *not* fit, with specifics, or (b) fold the work into the existing module.
+
+**When you find a deep-module red flag**, send the brief back with this instruction (adapt to the specific finding):
+
+> "The brief proposes [quote the specific shallow pattern]. This project is built from deep modules — small interface, large hidden body. A shallow module ships permanent overhead. Either fold the work into [name the existing deep module that could absorb it], or produce the full module proposal (interface surface, hidden complexity, depth justification, paths claimed) that proves this is genuinely a deep module. Read `docs/philosophy/deep-modules.md` before retrying."
+
+When the gate passes — both architectural quality and deep-module — record `✓ deep-module gate passed` in the swarm audit entry under `## Gate triggers`. When it fails, record the trigger and the retry.
+
 - **Time ceiling per agent.** If a run exceeds its rough budget (architect >1h, coder >2h, tester >1h, reviewer >30m), don't kill the agent (loses in-flight work) — surface the duration and ask whether to continue, redirect, or escalate (e.g. coder stuck → debugger).
 - **Architectural drift.** If the coder or tester surfaces a design choice not in the architect's brief, STOP, route to the architect for a decision before re-spawning. Coders making design calls inline is the failure mode the swarm exists to prevent.
 - **Midpoint coherence check** (full-feature swarms). After coder finishes, before tester spawns: are file paths and contracts the architect named present in the coder's output? If misaligned, escalate before spending tester tokens.

package/templates/protocols/end-of-session.md

@@ -84,7 +84,21 @@ Before committing, scan:
 - Cross-references resolve (no dead links)
 - Dates are right
 
-### 10. Commit
+### 10. Code-quality gate (only if staged diff touches source)
+
+If `git diff --cached --name-only` shows source files (`*.ts`, `*.tsx`, `*.js`, `*.jsx`, `*.sh`, `*.py` — NOT markdown, decisions, sessions, or registers), run this 7-point pass against the staged diff before committing. If only docs/registers are staged, skip the gate entirely.
+
+1. **Code-judo** — is there a reframing that *deletes* whole branches/helpers/layers rather than rearranging them? Push for the simpler model, not the cleaner version of the same model.
+2. **1k-line rule** — did any file cross 1000 lines? If yes, decompose first; don't ship the sprawl.
+3. **Spaghetti growth** — new ad-hoc conditionals, one-off booleans, or special-case branches bolted into unrelated flows? Push the logic behind its own abstraction.
+4. **Boundaries** — feature-specific logic leaking into shared paths; bespoke helpers duplicating a canonical one; logic landing in the wrong layer/package.
+5. **Types** — unnecessary `any` / `unknown` / optionality / casts masking the real contract? Make boundaries explicit.
+6. **Atomicity** — serial async where parallel is simpler and clearer; partial-update flows that can leave state half-applied.
+7. **Wrappers** — thin abstractions, identity passthroughs, or pass-through helpers adding indirection without buying clarity?
+
+If a finding is non-trivial, fix it inline or file a follow-up WU before committing. **Escalate to the full rubric** by invoking `/thermo-nuclear-code-quality-review` if the lite pass smells anything structural — the full skill is the "this should not ship as-is" reviewer; the 7-point pass above is the cheap pre-flight.
+
+### 11. Commit
 
 Single commit. Message format:
 

package/templates/protocols/wu-new.md

@@ -27,6 +27,30 @@ Also ask:
 
 - **Which persona is this for?** Show them the list from `docs/build/personas/`. If none yet, file a persona first via `/persona-new`.
 
+## Step 2.5 — Deep-module intake gate (mandatory, non-negotiable)
+
+> **This gate is the most important step in `/wu-new`. It is the single mechanism that prevents shallow-module sprawl as a long-running build progresses. Do not skip it. Do not abbreviate it. See [docs/philosophy/deep-modules.md](../../starter-kit/docs/philosophy/deep-modules.md) for the doctrine.**
+
+Before filing the work unit, the operator must declare which module owns it. List every entry in `docs/build/architecture/` (read the `_index.md` table) and ask:
+
+> *"Which existing module does this work unit live inside? Here's what we've got: [list each module + one-line `What this module does` summary]. Or — does this need a new module?"*
+
+**Three possible answers:**
+
+1. **"It belongs to existing module X."** Read `docs/build/architecture/X.md`. Check that the WU's responsibility actually fits inside X's `Hidden complexity` — not just that file paths overlap. If yes, set `Module: X` in the WU. If the WU adds new source paths, also add them to X's `## Paths claimed` section in the same conversation.
+
+2. **"It needs a new module Y."** STOP. Do not file the WU yet. Tell the operator: *"A new module needs an architect pass before this WU can be filed. Want me to walk through proposing module Y now — its interface surface, hidden complexity, depth justification — and file the architecture entry first? Then we file the WU against the new module."* On confirmation, run the architect through the new-module flow: produce `docs/build/architecture/Y.md` from `module-template.md`, populate every field including `Paths claimed`, then return here and file the WU with `Module: Y`.
+
+3. **"I'm not sure — it could go in X or be its own thing Y."** This is the most dangerous case. Default to **fits inside X** and tell the operator why: *"Splitting too early creates a shallow module that's permanent; folding into X is reversible later. Let's put it in X. If three more WUs land there and a coherent sub-responsibility emerges, the architect can split it then."* Only override this default if the architect has explicitly justified the split in the conversation.
+
+**Forbidden answers:**
+
+- *"It's just a small utility / helper / shared bit."* — Util grab-bags are shallow modules by definition. Tell the operator: *"There's no `utils` module in this project by design — small bits live inside the module whose hidden complexity needs them. Which module's hidden complexity does this work serve?"*
+- *"Let's figure it out during the build."* — The whole point of this gate is to decide upfront. Push back: *"The build agents need to know which module they're working inside before they start. Let's pick now — if it's wrong we can correct it before the coder spawns."*
+- *"Skip this for now, we'll come back to it."* — There is no skipping. The WU does not get a number, does not get filed, until `Module:` is set.
+
+**Set `Module:` in the WU file.** Both `001-template-simple.md` and `001-template-full.md` carry a `Module:` field in the header. The value is the architecture file slug (e.g., `auth`, `consolidation`, `morning-briefing`).
+
 ## Step 3 — Walk the full shape (only when --full or for infrastructure work)
 
 The full shape has the four fields above plus:

package/templates/starter-kit/docs/build/architecture/_index.md

@@ -13,12 +13,18 @@ The **architecture** register describes the major pieces of {{PROJECT_NAME}} and
 For each major piece of your project:
 
 - **What it does** — a paragraph in plain language
+- **Interface surface** — every public entry point, kept deliberately small
+- **Hidden complexity** — what the module encapsulates that callers don't need to think about
+- **Depth justification** — why this module's hidden body is genuinely large relative to its interface
+- **Paths claimed** — source-tree paths this module owns (read by the `check-module-discipline.sh` hook)
 - **Who's responsible for it** — which persona or role uses it most directly
 - **What it depends on** — other modules, external services, hardware
 - **What depends on it** — what would break if this module went away
 - **Open questions about it** — anything unresolved about its shape
 - **Links to relevant contracts** — what this module produces and consumes
 
+Every module in this register is a **deep module** by commitment. Shallow modules — pass-through wrappers, util grab-bags, micro-modules, premature splits — are rejected at the intake gate. See [deep-modules.md](../../philosophy/deep-modules.md) for the doctrine; the rule is enforced by the `/wu-new` intake gate, the `/build-wu` architectural quality gate, and the `check-module-discipline.sh` PreToolUse hook.
+
 Architecture files are *what's true about each piece*; they're not implementation specs. Implementation lives in code; this register lives in the catalogue.
 
 ## When the architecture register gets populated

package/templates/starter-kit/docs/build/architecture/module-template.md

@@ -12,6 +12,33 @@
 
 > Example: "The Overnight Consolidation module processes every interaction with a student during a school day and produces, by morning, a per-student plan ranked by need."
 
+## Interface surface
+
+> *Small by design. List every public entry point another module can call: function names, exported types, HTTP routes, CLI commands, message types. If this list runs longer than a screen, the interface is wide — the module is at risk of being shallow. See [deep-modules.md](../../philosophy/deep-modules.md).*
+
+- [public function / route / type]
+- [...]
+
+## Hidden complexity
+
+> *Large by design. List what this module encapsulates that callers do not have to think about: state, branching, external integrations, retry logic, validation, edge cases, persistence, ordering, concurrency. The depth ratio (hidden complexity ÷ interface surface) is what makes a module deep.*
+
+- [thing hidden from callers]
+- [...]
+
+## Depth justification
+
+> *Required for every module. Answer in two or three sentences: why is the hidden complexity above genuinely larger than the interface surface above? If you cannot answer this, the module is shallow — fold its work into an existing module instead of filing a new one.*
+
+[The depth argument.]
+
+## Paths claimed
+
+> *Required. List the source-tree paths this module owns. The PreToolUse hook (`check-module-discipline.sh`) reads this section and blocks writes to source files not claimed by any module. Use directory prefixes (`src/auth/`) or glob-style patterns (`src/auth/**`). One per line, as a bullet.*
+
+- `src/[module-slug]/`
+- [...]
+
 ## Who uses it directly
 
 [List the personas who interact with this module via UI/UX surfaces. Each as `[P001](../personas/P001-name.md)` with a one-line note on how they use it.]

package/templates/starter-kit/docs/build/work-units/001-template-full.md

@@ -3,6 +3,7 @@
 | Field | Value |
 | --- | --- |
 | Status | 🟡 in flight |
+| Module | [architecture slug — required; set at the `/wu-new` deep-module intake gate] |
 | Depends on | none |
 | Blocks | [WUs that cannot start until this lands] |
 | Implements | [the decision or pattern this realises] |

package/templates/starter-kit/docs/build/work-units/001-template-simple.md

@@ -4,6 +4,7 @@
 
 **Status:** 🔵 proposed / 🟡 in flight / 🟣 awaiting review / ✅ shipped / 🔴 blocked
 **For:** [persona handle and name — e.g. [P001 — name](../personas/P001-name.md)]
+**Module:** [architecture slug — e.g. [auth](../architecture/auth.md). Required. Set at the `/wu-new` deep-module intake gate.]
 **Last updated:** {{TODAY}}
 
 ## What's done when this ships

package/templates/starter-kit/docs/philosophy/_index.md

@@ -12,7 +12,7 @@ That is when a philosophy doc becomes worth writing. One short narrative-form do
 
 | Doc | Topic |
 | --- | --- |
-| _none yet — philosophy emerges as decisions accumulate_ | |
+| [deep-modules.md](deep-modules.md) | Every feature lives inside an existing deep module or constitutes a new one with stated interface, hidden complexity, and depth justification. Non-negotiable. |
 
 ## Pattern
 

package/templates/starter-kit/docs/philosophy/deep-modules.md

@@ -0,0 +1,82 @@
+# Deep modules
+
+> The architectural commitment that this project is built from **deep modules** — small interface, large hidden complexity — and never from shallow ones. This is the most load-bearing decision in the project's shape, and the rule cannot be broken as the build progresses.
+
+## What a deep module is
+
+A deep module is a chunk of the system with:
+
+- **A small interface** — few public functions, few public types, few entry points. What other modules need to know to use it is small.
+- **A large hidden body** — significant complexity, state, branching, integration with external systems, edge-case handling, all *behind* the interface.
+
+The asymmetry between interface and body is the **depth ratio**. A deep module hides a lot behind a little. A shallow module hides little behind a little — its interface is roughly as wide as its implementation, so the module is almost pure overhead.
+
+Ousterhout's *A Philosophy of Software Design* names this directly: **the best modules are deep**. They reduce the total cognitive load of the system because every caller pays a small interface cost in exchange for a large hidden cost they no longer have to think about.
+
+## What a shallow module looks like
+
+These are the failure modes this project rejects:
+
+- **The pass-through** — a module whose public methods each call exactly one method in another module, adding nothing. Wraps without hiding.
+- **The util / helper grab-bag** — `utils.ts`, `helpers/`, `common/`. A directory of unrelated functions sharing only the property that nobody knew where else to put them. No hidden complexity, no coherent responsibility.
+- **The leaky abstraction** — the interface exposes the implementation's data structures, internal types, or assumptions. Callers must understand the implementation to use the interface correctly. The hidden body is not actually hidden.
+- **The thin wrapper** — a module that exists to rename, re-export, or thinly adapt another module. Adds a layer of indirection without adding encapsulation.
+- **The micro-module** — three files, four functions, one responsibility that should have lived inside a larger module. The boundary itself becomes the overhead.
+- **The premature split** — taking a feature whose complexity could have been absorbed by an existing deep module and giving it its own module *just because it's new*. Splits cohesion without earning depth.
+
+When a shallow module appears, the system pays the interface cost (boundaries, contracts, imports, indirection) without earning the encapsulation benefit. Shallow modules accumulate; the system becomes a sprawl of thin layers that hide nothing and force every change to thread through many files.
+
+## The rule, in one sentence
+
+> **Every new feature added during the build either lives inside an existing deep module, or constitutes a new deep module with a stated interface, stated hidden complexity, and a stated depth justification. There is no third option.**
+
+This rule is non-negotiable. It applies to every work unit. It applies whether the work is greenfield or a follow-on. It applies whether the operator is in `lite`, `standard`, or `power` mode. It is enforced by the protocols (intake gate in `/wu-new`, architectural quality gate in `/build-wu`, audit by the reviewer) and by a Claude PreToolUse hook (`check-module-discipline.sh`) that blocks writes to source paths not claimed by any module.
+
+## How to apply the rule when filing a work unit
+
+When `/wu-new` runs, the operator is asked which module the work belongs to. Three answers are possible:
+
+1. **"It belongs to module X (existing)."** Check that the WU's responsibility actually fits inside X's hidden complexity — not just that the file paths happen to overlap. If yes, the WU's `Module:` field is set to `X` and the work proceeds. The architecture file for X is updated if the WU adds new paths or surfaces.
+
+2. **"It needs a new module Y."** The architect runs first, before the WU is filed. They produce a contract for Y: its small interface, its large hidden complexity, the depth justification. The new module is filed in `docs/build/architecture/Y.md`, the relevant contract(s) are filed in `docs/build/contracts/`, and only then is the WU filed with `Module: Y`.
+
+3. **"I'm not sure — it could go in X or it could be Y."** This is the most common case and the most dangerous. Default to **fits inside X** until the architect explicitly justifies the split. The cost of an under-split module is rework; the cost of an over-split system is permanent shallow sprawl that compounds. The first error is cheap to fix, the second is not.
+
+## How to apply the rule when designing
+
+The architect's brief, for any work unit, must answer three questions before the coder spawns:
+
+1. **Which module owns this?** Named, with a link to its architecture file.
+2. **What does the interface look like after this change?** The new public methods/exports/routes — explicit, small, named.
+3. **What complexity is hidden behind that interface?** The state, the branching, the external integrations, the edge cases the caller does not have to think about.
+
+If the third answer is small relative to the second, the design is shallow. The architect must either fold the work into an existing deep module (so the new complexity joins existing hidden complexity) or expand the hidden body (more is genuinely encapsulated here) — never ship a shallow new module.
+
+## How to apply the rule during implementation
+
+The coder may not create a new top-level source directory unless a corresponding architecture file claims it under `## Paths claimed`. The PreToolUse hook enforces this. If the coder finds themselves wanting to create `src/foo/` mid-implementation, that is a signal — pause, route back to the architect, get the module filed (or get `foo/` claimed by an existing module) before the file is written.
+
+This is friction by design. Most shallow modules are born from a coder's mid-flight decision to "just split this out." The hook makes that decision visible and routes it through the architect.
+
+## How to apply the rule during review
+
+The reviewer reads every change against three checks:
+
+- **Did this work create a new module?** If yes, is the architecture file present, is the interface small, is the hidden complexity large, is the depth justification recorded?
+- **Did this work extend an existing module?** If yes, does the extension actually live inside the module's hidden complexity — or is it leaking into the interface in a way that makes the module shallower than it was?
+- **Did this work add code to an unclaimed path?** If yes, the hook should already have caught it; if it didn't, that's a hook gap to file.
+
+A change that creates or worsens a shallow module is a `REQUEST CHANGES`, not an `APPROVE`. Speed of delivery is never an acceptable reason to ship a shallow module — see the no-shortcuts policy that already governs the architect's brief.
+
+## Why this matters more than most architectural rules
+
+Most architectural commitments can be re-evaluated when the situation changes. Module depth cannot. A shallow module ships interface contracts, file paths, imports, and tests that callers build against — un-splitting it later means rewriting all of them. By the time the cost of the wrong split is felt, the cost of fixing it is large enough that it never gets fixed. The shallow split becomes permanent.
+
+So the discipline is **enforce at intake**, not at cleanup. The intake gate is the cheap moment. Every other moment is more expensive.
+
+## Related
+
+- The no-shortcuts policy (architect.md, build-wu.md) — shallow modules are a class of shortcut
+- The design-it-twice rule (architect.md) — one of the two designs must explore folding into an existing module
+- The module template (`../build/architecture/module-template.md`) — the contract every new module must fill in
+- The module-discipline hook (`.claude/hooks/check-module-discipline.sh`) — the mechanical gate