@polymorphism-tech/morph-spec 8.33.0 → 8.34.2

package/framework/hooks/claude-code/core/worktree-create.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * worktree-create.js — WorktreeCreate hook
+ *
+ * Event: WorktreeCreate (fires for `claude -w`, the EnterWorktree tool, and
+ * `Agent isolation:"worktree"` — measured, not assumed).
+ *
+ * Claude Code's native worktree is a bare `git worktree add` somewhere under
+ * `.claude/worktrees/`: no infra junctions (so no hooks run in there), no port
+ * block, no identity, invisible to the fleet. When this hook is registered it
+ * REPLACES that logic entirely: it must print the path of the tree it created
+ * as the last non-empty stdout line and exit 0; any non-zero exit fails the
+ * creation. It cannot return JSON — the standalone tail below is therefore
+ * NOT `runStandalone` (which prints a JSON verdict). Diagnostics go to stderr.
+ *
+ * What it does:
+ *   1. root = the PRIMARY root of the repo `payload.cwd` is in (never a
+ *      secondary worktree — a tree under a tree is the fleet-invisible shape).
+ *   2. name → kebab slug (`Bold_Oak` → `bold-oak`, `agent-a1b2` stays).
+ *   3. feature or task? `<root>/.morph/features/<n>/feature.json` exists, or
+ *      branch `morph/<n>` exists → `morph-spec worktree setup <n>`; otherwise
+ *      `morph-spec worktree provision <n> [--base <ref>]`.
+ *   4. `worktree.baseRef` from the merged settings (`~/.claude/settings.json`
+ *      < `<root>/.claude/settings.json` < `<root>/.claude/settings.local.json`):
+ *      `"head"` → the current branch (or sha) of `payload.cwd`; anything else
+ *      → the repo's default branch (the CLI's own default).
+ *   5. CLI exit 0 or 2 (already exists) → its `path`. Exit 1/3 → error.
+ *      CLI unavailable → in-hook git fallback that still lands the tree under
+ *      `<root>/worktrees/<n>` on `morph-task/<n>` (degraded: no junctions, no
+ *      ports — but never outside the governed directory).
+ *
+ * `stateExists(root)` gate: outside a morph project (no `.morph/state.json`
+ * and no feature.json) there is nothing to govern — the same in-hook git
+ * fallback runs, so a non-morph repo with this hook installed still gets a
+ * worktree instead of a failed creation.
+ */
+
+import { existsSync, mkdirSync, readFileSync } from 'fs';
+import { execFileSync } from 'child_process';
+import { dirname, join, resolve } from 'path';
+import { homedir } from 'os';
+import { stateExists } from '../../shared/state-reader.js';
+import { resolveGitCommonDir } from '../../shared/git-paths.js';
+import { runMorphSpec } from '../../shared/morph-cli.js';
+
+const WORKTREES_DIR = 'worktrees';
+
+const fwd = (p) => String(p).replace(/\\/g, '/');
+
+function git(args, cwd) {
+  return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
+}
+
+/**
+ * The primary root of the repo containing `startDir`. `git worktree list`'s
+ * first entry is the primary checkout, from any worktree; the pure-filesystem
+ * common-dir resolver is the no-subprocess fallback. Null outside a repo.
+ */
+export function resolvePrimaryRoot(startDir) {
+  try {
+    const first = git(['worktree', 'list', '--porcelain'], startDir).split('\n').find((l) => l.startsWith('worktree '));
+    if (first) return fwd(first.slice('worktree '.length).trim());
+  } catch { /* fall through */ }
+  const common = resolveGitCommonDir(startDir);
+  return common ? fwd(dirname(common)) : null;
+}
+
+/** `Bold_Oak` → `bold-oak`; empty → a timestamped slug. */
+export function slugify(name) {
+  const slug = String(name || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug || `wt-${Date.now().toString(36)}`;
+}
+
+function readJsonSafe(path) {
+  try { return JSON.parse(readFileSync(path, 'utf8').replace(/^/, '')); } catch { return null; }
+}
+
+/**
+ * `worktree.baseRef` across the three settings layers, last one wins.
+ * Fail-open per file. Returns `'fresh'` (the documented default) when unset.
+ */
+export function readBaseRefSetting(root, home = homedir()) {
+  let value = 'fresh';
+  for (const p of [
+    join(home, '.claude', 'settings.json'),
+    join(root, '.claude', 'settings.json'),
+    join(root, '.claude', 'settings.local.json'),
+  ]) {
+    const s = readJsonSafe(p);
+    const v = s?.worktree?.baseRef;
+    if (typeof v === 'string' && v) value = v;
+  }
+  return value;
+}
+
+/** The ref `baseRef:"head"` means: the branch checked out in `cwd`, or its sha. */
+function headRef(cwd) {
+  try {
+    const name = git(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+    if (name && name !== 'HEAD') return name;
+    return git(['rev-parse', 'HEAD'], cwd) || null;
+  } catch {
+    return null;
+  }
+}
+
+function isKnownFeature(root, name) {
+  if (existsSync(join(root, '.morph', 'features', name, 'feature.json'))) return true;
+  try {
+    git(['show-ref', '--verify', '--quiet', `refs/heads/morph/${name}`], root);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function defaultBranch(root) {
+  try {
+    const m = git(['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD'], root).match(/^refs\/remotes\/origin\/(.+)$/);
+    if (m) return m[1];
+  } catch { /* no origin/HEAD */ }
+  for (const c of ['main', 'master']) {
+    try { git(['show-ref', '--verify', '--quiet', `refs/heads/${c}`], root); return c; } catch { /* next */ }
+  }
+  return null;
+}
+
+/**
+ * Degraded path — the CLI is not reachable, but the tree still has to land
+ * in the governed directory on the governed branch namespace.
+ */
+function gitFallback(root, name, base) {
+  const branch = `morph-task/${name}`;
+  const path = `${root}/${WORKTREES_DIR}/${name}`;
+  if (existsSync(path)) return { path };
+  try { git(['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], root); }
+  catch {
+    const from = base || defaultBranch(root);
+    git(from ? ['branch', branch, from] : ['branch', branch], root);
+  }
+  mkdirSync(join(root, WORKTREES_DIR), { recursive: true });
+  git(['worktree', 'add', path, branch], root);
+  return { path };
+}
+
+/**
+ * @param {object} payload - parsed WorktreeCreate stdin payload
+ *   ({ session_id, cwd, hook_event_name, name })
+ * @returns {Promise<{ path: string }|{ error: string }>}
+ */
+export async function run(payload) {
+  const start = payload?.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const root = resolvePrimaryRoot(start) || (process.env.CLAUDE_PROJECT_DIR ? fwd(resolve(process.env.CLAUDE_PROJECT_DIR)) : null);
+  if (!root) return { error: `worktree-create: "${start}" is not inside a git repository` };
+
+  const name = slugify(payload?.name);
+  const baseSetting = readBaseRefSetting(root);
+  const base = baseSetting === 'head' ? headRef(start) : null;
+
+  // Outside a morph project there is nothing to govern beyond WHERE the tree
+  // lands — plain git, under <root>/worktrees/.
+  if (!stateExists(root)) {
+    try { return gitFallback(root, name, base); }
+    catch (err) { return { error: `worktree-create: ${err?.message || err}` }; }
+  }
+
+  const args = isKnownFeature(root, name)
+    ? ['worktree', 'setup', name, '--json']
+    : ['worktree', 'provision', name, '--json', ...(base ? ['--base', base] : [])];
+
+  const r = runMorphSpec(args, { cwd: root });
+  if (r.unavailable) {
+    process.stderr.write('worktree-create: morph-spec CLI not found — creating the tree with plain git under worktrees/ (no infra links, no port block). Run `morph-spec worktree link --all` inside it.\n');
+    try { return gitFallback(root, name, base); }
+    catch (err) { return { error: `worktree-create: ${err?.message || err}` }; }
+  }
+  if (r.stderr?.trim()) process.stderr.write(r.stderr);
+
+  const ok = r.code === 0 || r.code === 2;
+  const path = r.json?.path;
+  if (ok && path && !r.json?.error) return { path: fwd(path) };
+  const why = r.json?.error || r.json?.hint || r.stderr?.trim() || `exit ${r.code}`;
+  return { error: `worktree-create: morph-spec ${args.slice(0, 2).join(' ')} ${name} failed — ${why}` };
+}
+
+// Standalone tail — NOT runStandalone(): this event's contract is "path on
+// stdout, exit 0" / "non-zero exit", never a JSON verdict.
+if (!process.env.MORPH_HOOK_CHAINED) {
+  const { readStdin } = await import('../../shared/stdin-reader.js');
+  let result;
+  try {
+    result = await run(await readStdin());
+  } catch (err) {
+    result = { error: `worktree-create: ${err?.message || err}` };
+  }
+  if (result?.path) {
+    process.stdout.write(`${result.path}\n`);
+    process.exit(0);
+  }
+  process.stderr.write(`${result?.error || 'worktree-create: no path produced'}\n`);
+  process.exit(1);
+}

package/framework/hooks/claude-code/core/worktree-env-inject.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * worktree-env-inject.js — PreToolUse hook (Bash matcher), last link of the
+ * Bash chain.
+ *
+ * `.morph/worktree.env` used to be a manifest nobody executed: SessionStart
+ * printed the port block and the model was expected to pass `PORT` by hand
+ * every time it started a dev server. Two worktrees whose sessions forgot
+ * collided on 3000 — a runtime clash dressed as a broken app. This hook makes
+ * the block reach the process deterministically: when the command is a
+ * dev-server / compose / spec launcher and the cwd is a worktree that owns a
+ * manifest, the command is rewritten to `export K='V' …; <command>` via
+ * `updatedInput`, and the rewrite is named in `additionalContext`.
+ *
+ * Scope is deliberately narrow: only launcher-shaped commands, only when the
+ * command does not already set a layout key itself (`PORT=…`, `--port`,
+ * `compose -p`), only for the Bash tool. Everything else passes untouched.
+ *
+ * Fail-open: no state, no manifest, unreadable manifest → null (pass).
+ */
+
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { stateExists } from '../../shared/state-reader.js';
+import { updatedInputResult, runStandalone } from '../../shared/hook-response.js';
+import { loadEnvFile } from '../../shared/e2e-check.js';
+
+/** Commands that start a server or a stack and therefore need the block. */
+const LAUNCHER_RE = /\b(?:(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:dev|start)\b|next\s+(?:dev|start)\b|vite\b|dotnet\s+(?:run|watch)\b|docker(?:\s+|-)compose\b|playwright\s+test\b)/;
+
+/** The command already chose its own port/project — respect it. */
+const SELF_CONFIGURED_RE = /(?:^|[\s;&|])(?:PORT|API_PORT|POSTGRES_PORT|COMPOSE_PROJECT_NAME|ASPNETCORE_URLS)=|--port\b|(?:^|\s)-p\s+\d|compose\b[^|;&]*\s-p\s/;
+
+/** Keys the layout owns; anything else in the manifest is left alone. */
+const LAYOUT_KEYS = ['COMPOSE_PROJECT_NAME', 'MORPH_PORT_BASE', 'MORPH_PORT_RANGE', 'PORT', 'API_PORT', 'POSTGRES_PORT', 'REDIS_PORT', 'ASPNETCORE_URLS', 'PLAYWRIGHT_BASE_URL'];
+
+/** POSIX single-quote, safe for Git Bash on Windows too. */
+function shq(v) {
+  return `'${String(v).replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * Pure decision: the rewritten command, or null when nothing should change.
+ * @param {string} command
+ * @param {Record<string,string>} env - parsed manifest
+ * @returns {{ command: string, injected: string[] }|null}
+ */
+export function rewriteCommand(command, env) {
+  if (!command || !LAUNCHER_RE.test(command)) return null;
+  if (SELF_CONFIGURED_RE.test(command)) return null;
+  const pairs = LAYOUT_KEYS.filter((k) => env[k]).map((k) => [k, env[k]]);
+  if (!pairs.some(([k]) => k === 'PORT')) return null;
+  // The web tier's URL is what the spec suite needs; derive it once here.
+  if (!env.PLAYWRIGHT_BASE_URL) pairs.push(['PLAYWRIGHT_BASE_URL', `http://localhost:${env.PORT}`]);
+  const prefix = `export ${pairs.map(([k, v]) => `${k}=${shq(v)}`).join(' ')}; `;
+  return { command: prefix + command, injected: pairs.map(([k, v]) => `${k}=${v}`) };
+}
+
+/**
+ * @param {object} payload - parsed PreToolUse stdin payload (Bash matcher)
+ * @returns {Promise<object|null>} an updatedInput result, or null (pass).
+ */
+export async function run(payload) {
+  try {
+    if (payload?.tool_name && payload.tool_name !== 'Bash') return null;
+    if (!stateExists()) return null;
+    const command = payload?.tool_input?.command || '';
+    if (!command) return null;
+
+    const dir = payload?.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+    const manifest = join(dir, '.morph', 'worktree.env');
+    if (!existsSync(manifest)) return null;
+
+    const rewritten = rewriteCommand(command, loadEnvFile(manifest));
+    if (!rewritten) return null;
+
+    return updatedInputResult(
+      { ...payload.tool_input, command: rewritten.command },
+      'PreToolUse',
+      `🔌 worktree env injetado (.morph/worktree.env): ${rewritten.injected.join(' ')}`,
+    );
+  } catch {
+    return null;
+  }
+}
+
+await runStandalone(run);

package/framework/hooks/claude-code/core/worktree-remove.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * worktree-remove.js — WorktreeRemove hook
+ *
+ * Event: WorktreeRemove (Claude Code's own cleanup of a tree it created via
+ * `claude -w` / EnterWorktree / Agent isolation). Input carries
+ * `worktree_path` (absolute). No decision control, output ignored — this hook
+ * ALWAYS exits 0.
+ *
+ * Why it exists: Claude Code's native removal is a raw `git worktree remove`,
+ * which FOLLOWS the infra junctions the WorktreeCreate hook put in that tree
+ * and empties the primary root's `.claude/` and `.morph/framework/`. This
+ * hook routes the removal through `morph-spec worktree remove --target
+ * --if-clean` instead: junctions dropped first, PROVE-or-DECLINE, and a tree
+ * holding uncommitted work is left alone (Claude Code's notion of "clean" is
+ * not the user's).
+ *
+ * Secondary net: in headless runs the event was observed NOT to fire; the
+ * PreToolUse guard (block-destructive-worktree-removal) stays the primary
+ * defense. Fail-open everywhere — diagnostics to stderr, never a throw, never
+ * a non-zero exit.
+ */
+
+import { existsSync } from 'fs';
+import { execFileSync } from 'child_process';
+import { dirname, resolve } from 'path';
+import { stateExists } from '../../shared/state-reader.js';
+import { resolveGitCommonDir } from '../../shared/git-paths.js';
+import { runMorphSpec } from '../../shared/morph-cli.js';
+
+const fwd = (p) => String(p).replace(/\\/g, '/');
+
+function primaryRoot(startDir) {
+  try {
+    const out = execFileSync('git', ['worktree', 'list', '--porcelain'], { cwd: startDir, stdio: ['ignore', 'pipe', 'pipe'] }).toString();
+    const first = out.split('\n').find((l) => l.startsWith('worktree '));
+    if (first) return fwd(first.slice('worktree '.length).trim());
+  } catch { /* fall through */ }
+  const common = resolveGitCommonDir(startDir);
+  return common ? fwd(dirname(common)) : null;
+}
+
+/**
+ * @param {object} payload - parsed WorktreeRemove stdin payload ({ cwd, worktree_path })
+ * @returns {Promise<null>} always null — the event ignores output
+ */
+export async function run(payload) {
+  try {
+    const target = payload?.worktree_path;
+    if (!target || !existsSync(target)) return null;
+
+    const start = payload?.cwd || process.env.CLAUDE_PROJECT_DIR || dirname(resolve(target));
+    const root = primaryRoot(start) || primaryRoot(dirname(resolve(target)));
+    if (!root) return null;
+    // Nothing to govern outside a morph project — and never a raw removal
+    // from here either: the tree is simply left for git's own cleanup.
+    if (!stateExists(root)) return null;
+
+    const r = runMorphSpec(['worktree', 'remove', '--target', fwd(resolve(target)), '--if-clean', '--json'], { cwd: root });
+    if (r.unavailable) {
+      process.stderr.write(`worktree-remove: morph-spec CLI not found — "${target}" left in place (remove it with \`morph-spec worktree remove --target\`, never with raw git: it follows the infra junctions out).\n`);
+      return null;
+    }
+    if (!r.ok) {
+      const why = r.json?.error || r.json?.hint || r.stderr?.trim() || `exit ${r.code}`;
+      process.stderr.write(`worktree-remove: "${target}" NOT removed — ${why}\n`);
+    }
+    return null;
+  } catch (err) {
+    process.stderr.write(`worktree-remove: ${err?.message || err}\n`);
+    return null;
+  }
+}
+
+// Standalone tail: output is ignored by this event, so nothing is printed;
+// the exit code is always 0.
+if (!process.env.MORPH_HOOK_CHAINED) {
+  const { readStdin } = await import('../../shared/stdin-reader.js');
+  try { await run(await readStdin()); } catch { /* fail-open */ }
+  process.exit(0);
+}

package/framework/hooks/claude-code/statusline.sh

@@ -1,11 +1,11 @@
-#!/usr/bin/env bash
-# morph-spec statusline — installed globally to ~/.claude/statusline.sh
-# Claude Code invokes this with JSON via stdin after each response.
-# Requires: Python 3 available as `python3` or `python` on PATH.
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-if command -v python3 &>/dev/null; then
-  python3 "${SCRIPT_DIR}/statusline.py" 2>/dev/null || true
-elif command -v python &>/dev/null; then
-  python "${SCRIPT_DIR}/statusline.py" 2>/dev/null || true
-fi
+#!/usr/bin/env bash
+# morph-spec statusline — installed globally to ~/.claude/statusline.sh
+# Claude Code invokes this with JSON via stdin after each response.
+# Requires: Python 3 available as `python3` or `python` on PATH.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if command -v python3 &>/dev/null; then
+  python3 "${SCRIPT_DIR}/statusline.py" 2>/dev/null || true
+elif command -v python &>/dev/null; then
+  python "${SCRIPT_DIR}/statusline.py" 2>/dev/null || true
+fi

package/framework/hooks/git/commit-msg/conventional-commits.sh

@@ -1,33 +1,33 @@
-#!/usr/bin/env bash
-# Scope: universal | Validates commit message format (Conventional Commits)
-# MORPH-SPEC Commit Message Hook
-# Enforces Conventional Commits specification
-
-COMMIT_MSG_FILE="$1"
-COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")
-
-# Conventional Commits pattern: type(scope): description
-# Types: feat, fix, docs, style, refactor, perf, test, chore, build, ci, revert
-PATTERN="^(feat|fix|docs|style|refactor|perf|test|chore|build|ci|revert)(\(.+\))?: .{1,100}"
-
-if ! echo "$COMMIT_MSG" | grep -qE "$PATTERN"; then
-  echo "❌ Invalid commit message format!"
-  echo ""
-  echo "Required format: <type>(<scope>): <description>"
-  echo ""
-  echo "Types: feat, fix, docs, style, refactor, perf, test, chore, build, ci, revert"
-  echo ""
-  echo "Examples:"
-  echo "  feat(auth): add JWT refresh token rotation"
-  echo "  fix(api): resolve null reference in UserService"
-  echo "  docs(readme): update installation instructions"
-  echo ""
-  echo "Your message:"
-  echo "  $COMMIT_MSG"
-  echo ""
-  echo "Override with: git commit --no-verify"
-  exit 1
-fi
-
-echo "✅ Commit message format valid"
-exit 0
+#!/usr/bin/env bash
+# Scope: universal | Validates commit message format (Conventional Commits)
+# MORPH-SPEC Commit Message Hook
+# Enforces Conventional Commits specification
+
+COMMIT_MSG_FILE="$1"
+COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")
+
+# Conventional Commits pattern: type(scope): description
+# Types: feat, fix, docs, style, refactor, perf, test, chore, build, ci, revert
+PATTERN="^(feat|fix|docs|style|refactor|perf|test|chore|build|ci|revert)(\(.+\))?: .{1,100}"
+
+if ! echo "$COMMIT_MSG" | grep -qE "$PATTERN"; then
+  echo "❌ Invalid commit message format!"
+  echo ""
+  echo "Required format: <type>(<scope>): <description>"
+  echo ""
+  echo "Types: feat, fix, docs, style, refactor, perf, test, chore, build, ci, revert"
+  echo ""
+  echo "Examples:"
+  echo "  feat(auth): add JWT refresh token rotation"
+  echo "  fix(api): resolve null reference in UserService"
+  echo "  docs(readme): update installation instructions"
+  echo ""
+  echo "Your message:"
+  echo "  $COMMIT_MSG"
+  echo ""
+  echo "Override with: git commit --no-verify"
+  exit 1
+fi
+
+echo "✅ Commit message format valid"
+exit 0

package/framework/hooks/git/pre-commit/agents.sh

@@ -1,25 +1,25 @@
-#!/bin/bash
-# Scope: universal | Validates agents.json Schema
-# MORPH-SPEC Pre-Commit Hook: Agent Configuration Validation
-# Uses validate-agents.js to check agents.json
-
-echo "🤖 Validating agent configuration..."
-
-# Check if agents.json is being modified
-if git diff --cached --name-only | grep -q 'agents\.json$'; then
-  echo "Detected changes to agents.json"
-
-  # Run validator
-  if ! morph-spec validate-agents-skills; then
-    echo ""
-    echo "❌ COMMIT BLOCKED: agents.json validation failed"
-    echo "   Fix errors above before committing"
-    exit 1
-  fi
-
-  echo "✓ agents.json is valid"
-else
-  echo "✓ No changes to agents.json"
-fi
-
-exit 0
+#!/bin/bash
+# Scope: universal | Validates agents.json Schema
+# MORPH-SPEC Pre-Commit Hook: Agent Configuration Validation
+# Uses validate-agents.js to check agents.json
+
+echo "🤖 Validating agent configuration..."
+
+# Check if agents.json is being modified
+if git diff --cached --name-only | grep -q 'agents\.json$'; then
+  echo "Detected changes to agents.json"
+
+  # Run validator
+  if ! morph-spec validate-agents-skills; then
+    echo ""
+    echo "❌ COMMIT BLOCKED: agents.json validation failed"
+    echo "   Fix errors above before committing"
+    exit 1
+  fi
+
+  echo "✓ agents.json is valid"
+else
+  echo "✓ No changes to agents.json"
+fi
+
+exit 0

package/framework/hooks/git/pre-commit/orchestrator.sh

@@ -1,64 +1,64 @@
-#!/usr/bin/env bash
-# Scope: universal | Orchestrates framework + stack-specific pre-commit hooks
-# MORPH-SPEC Master Pre-Commit Hook
-# Runs universal framework hooks + stack-specific hooks in sequence
-
-echo "╔════════════════════════════════════════════════╗"
-echo "║     MORPH-SPEC PRE-COMMIT VALIDATION           ║"
-echo "╚════════════════════════════════════════════════╝"
-echo ""
-
-FRAMEWORK_HOOKS_DIR="$(dirname "$0")"
-STACK_HOOKS_DIR=".morph/hooks/pre-commit"
-
-HAS_FAILURES=false
-
-# Run framework hooks (universal - all stacks)
-echo "📦 Running framework hooks (universal)..."
-for hook in "$FRAMEWORK_HOOKS_DIR"/*.sh; do
-  # Skip orchestrator itself
-  if [[ "$hook" == */orchestrator.sh ]]; then
-    continue
-  fi
-
-  if [[ -f "$hook" ]]; then
-    hook_name=$(basename "$hook")
-    echo "─────────────────────────────────────────────────"
-    if ! bash "$hook"; then
-      HAS_FAILURES=true
-      echo "❌ Framework hook failed: $hook_name"
-    fi
-    echo ""
-  fi
-done
-
-# Run stack-specific hooks (if exist)
-if [[ -d "$STACK_HOOKS_DIR" ]]; then
-  echo "🎯 Running stack-specific hooks..."
-  for hook in "$STACK_HOOKS_DIR"/*.sh; do
-    if [[ -f "$hook" ]]; then
-      hook_name=$(basename "$hook")
-      echo "─────────────────────────────────────────────────"
-      if ! bash "$hook"; then
-        HAS_FAILURES=true
-        echo "❌ Stack hook failed: $hook_name"
-      fi
-      echo ""
-    fi
-  done
-else
-  echo "ℹ️  No stack-specific hooks found (optional)"
-  echo ""
-fi
-
-echo "═════════════════════════════════════════════════"
-
-if [[ "$HAS_FAILURES" == "true" ]]; then
-  echo "❌ PRE-COMMIT VALIDATION FAILED"
-  echo "   Fix errors above before committing"
-  echo "   Or use: git commit --no-verify to skip"
-  exit 1
-fi
-
-echo "✅ ALL PRE-COMMIT VALIDATIONS PASSED"
-exit 0
+#!/usr/bin/env bash
+# Scope: universal | Orchestrates framework + stack-specific pre-commit hooks
+# MORPH-SPEC Master Pre-Commit Hook
+# Runs universal framework hooks + stack-specific hooks in sequence
+
+echo "╔════════════════════════════════════════════════╗"
+echo "║     MORPH-SPEC PRE-COMMIT VALIDATION           ║"
+echo "╚════════════════════════════════════════════════╝"
+echo ""
+
+FRAMEWORK_HOOKS_DIR="$(dirname "$0")"
+STACK_HOOKS_DIR=".morph/hooks/pre-commit"
+
+HAS_FAILURES=false
+
+# Run framework hooks (universal - all stacks)
+echo "📦 Running framework hooks (universal)..."
+for hook in "$FRAMEWORK_HOOKS_DIR"/*.sh; do
+  # Skip orchestrator itself
+  if [[ "$hook" == */orchestrator.sh ]]; then
+    continue
+  fi
+
+  if [[ -f "$hook" ]]; then
+    hook_name=$(basename "$hook")
+    echo "─────────────────────────────────────────────────"
+    if ! bash "$hook"; then
+      HAS_FAILURES=true
+      echo "❌ Framework hook failed: $hook_name"
+    fi
+    echo ""
+  fi
+done
+
+# Run stack-specific hooks (if exist)
+if [[ -d "$STACK_HOOKS_DIR" ]]; then
+  echo "🎯 Running stack-specific hooks..."
+  for hook in "$STACK_HOOKS_DIR"/*.sh; do
+    if [[ -f "$hook" ]]; then
+      hook_name=$(basename "$hook")
+      echo "─────────────────────────────────────────────────"
+      if ! bash "$hook"; then
+        HAS_FAILURES=true
+        echo "❌ Stack hook failed: $hook_name"
+      fi
+      echo ""
+    fi
+  done
+else
+  echo "ℹ️  No stack-specific hooks found (optional)"
+  echo ""
+fi
+
+echo "═════════════════════════════════════════════════"
+
+if [[ "$HAS_FAILURES" == "true" ]]; then
+  echo "❌ PRE-COMMIT VALIDATION FAILED"
+  echo "   Fix errors above before committing"
+  echo "   Or use: git commit --no-verify to skip"
+  exit 1
+fi
+
+echo "✅ ALL PRE-COMMIT VALIDATIONS PASSED"
+exit 0