@slamb2k/mad-skills 2.0.11 → 2.0.13

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mad-skills",
   "description": "AI-assisted planning, development and governance tools",
-  "version": "2.0.11",
+  "version": "2.0.13",
   "author": {
     "name": "slamb2k",
     "url": "https://github.com/slamb2k"

package/hooks/hooks.json

@@ -1,26 +1,11 @@
 {
   "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "./hooks/session-guard.sh",
-            "timeout": 30000
-          }
-        ]
-      }
-    ],
-    "UserPromptSubmit": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "./hooks/session-guard-prompt.sh",
-            "timeout": 10000
-          }
-        ]
-      }
-    ]
+    "SessionStart": [{
+      "matcher": "startup|clear|compact",
+      "hooks": [{ "type": "command", "command": "node ./hooks/session-guard.cjs check", "timeout": 30 }]
+    }],
+    "UserPromptSubmit": [{
+      "hooks": [{ "type": "command", "command": "node ./hooks/session-guard.cjs remind", "timeout": 10 }]
+    }]
   }
 }

package/hooks/lib/banner.cjs

@@ -0,0 +1,27 @@
+'use strict';
+
+const config = require('./config.cjs');
+
+// prettier-ignore
+const BANNER_LINES = [
+  'M"""""`\'"""`YM                dP    MP""""""`MM dP       oo dP dP',
+  'M  mm.  mm.  M                88    M  mmmmm..M 88          88 88',
+  'M  MMM  MMM  M .d8888b. .d888b88    M.      `YM 88  .dP  dP 88 88 .d8888b.',
+  'M  MMM  MMM  M 88\'  `88 88\'  `88    MMMMMMM.  M 88888"   88 88 88 Y8ooooo.',
+  'M  MMM  MMM  M 88.  .88 88.  .88    M. .MMM\'  M 88  `8b. 88 88 88       88',
+  'M  MMM  MMM  M `88888P8 `88888P8    Mb.     .dM dP   `YP dP dP dP `88888P\'',
+  'MMMMMMMMMMMMMM                      MMMMMMMMMMM',
+];
+
+const SEPARATOR = '\u2500'.repeat(70);
+
+function getBanner() {
+  return [
+    ...BANNER_LINES,
+    SEPARATOR,
+    ` Session Guard v${config.version}`,
+    SEPARATOR,
+  ].join('\n');
+}
+
+module.exports = { getBanner, BANNER_MARKER: 'MMMMMMMMMMMMMM' };

package/hooks/lib/config.cjs

@@ -0,0 +1,56 @@
+'use strict';
+
+const { readFileSync } = require('fs');
+const { join, dirname } = require('path');
+
+function getVersion() {
+  // Walk up from lib/ to find package.json (mad-skills plugin root)
+  const hooksDir = dirname(__dirname);
+  for (const candidate of [
+    join(hooksDir, '..', 'package.json'),
+    join(hooksDir, '..', '.claude-plugin', 'plugin.json'),
+  ]) {
+    try {
+      return JSON.parse(readFileSync(candidate, 'utf8')).version;
+    } catch {}
+  }
+  return '0.0.0-dev';
+}
+
+module.exports = {
+  version: getVersion(),
+
+  staleness: {
+    threshold: 3,
+    age: { warn: 7, critical: 14 },
+    commits: { warn: 20, critical: 50 },
+    depDrift: { minor: 0, major: 5 },
+    topLevelFiles: 3,
+    lockFileDays: 7,
+    undocumentedDeps: 5,
+    missingDirs: { few: 0, many: 2 },
+  },
+
+  monorepo: {
+    markers: [
+      'pnpm-workspace.yaml', 'lerna.json', 'nx.json',
+      'turbo.json', 'rush.json',
+    ],
+    dirs: ['packages', 'apps', 'services', 'libs', 'modules', 'projects'],
+    minSignals: 2,
+  },
+
+  configFiles: [
+    'tsconfig.json', '.env.example', 'docker-compose.yml',
+    'Dockerfile', 'Makefile', 'Cargo.toml', 'go.mod',
+  ],
+
+  lockFiles: [
+    'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml',
+    'bun.lock', 'Cargo.lock', 'poetry.lock', 'uv.lock',
+  ],
+
+  pythonFiles: ['pyproject.toml', 'requirements.txt', 'setup.py'],
+
+  taskList: { minCommits: 20, minFiles: 30 },
+};

package/hooks/lib/git-checks.cjs

@@ -0,0 +1,118 @@
+'use strict';
+
+const { existsSync } = require('fs');
+const { join, dirname, basename } = require('path');
+const config = require('./config.cjs');
+const { git, readJson, countFiles } = require('./utils.cjs');
+
+/**
+ * Validate git repository state.
+ * Returns { gitRoot: string|null }.
+ */
+function checkGit(projectDir, output) {
+  const gitRoot = git('rev-parse --show-toplevel', projectDir);
+
+  if (gitRoot === null) {
+    output.add('[SESSION GUARD] \u26A0\uFE0F  This directory is NOT tracked by Git.');
+    output.addQuestion(
+      'This directory isn\'t inside a Git repository. What would you like to do?',
+      'single_select',
+      [
+        '"Initialise Git" \u2014 run `git init` and suggest creating .gitignore',
+        '"Skip" \u2014 continue without version control',
+      ],
+    );
+    return { gitRoot: null };
+  }
+
+  if (gitRoot !== projectDir) {
+    checkNestedGit(projectDir, gitRoot, output);
+  }
+
+  return { gitRoot };
+}
+
+function checkNestedGit(projectDir, gitRoot, output) {
+  // Calculate depth
+  let depth = 0;
+  let check = projectDir;
+  while (check !== gitRoot && check !== '/') {
+    check = dirname(check);
+    depth++;
+  }
+
+  const signals = detectMonorepo(gitRoot);
+  const relative = projectDir.slice(gitRoot.length + 1);
+
+  if (signals.length >= config.monorepo.minSignals) {
+    output.add(`[SESSION GUARD] \u2139\uFE0F  Git root is ${depth} level(s) above CWD.`);
+    output.add(`  Git root:    ${gitRoot}`);
+    output.add(`  Working dir: ${projectDir}`);
+    output.add(`  Monorepo signals: ${signals.join(', ')}`);
+    output.addQuestion(
+      `Git root is at \`${gitRoot}\` (monorepo). Working in \`${relative}\`. Correct context?`,
+      'single_select',
+      ['"Yes, correct package"', '"No, switch to repo root"'],
+      'low',
+    );
+  } else {
+    const fileCount = countFiles(gitRoot);
+    output.add(`[SESSION GUARD] \u26A0\uFE0F  Git root is ${depth} level(s) above CWD \u2014 does NOT look like a monorepo.`);
+    output.add(`  Git root:    ${gitRoot} (${fileCount} files)`);
+    output.add(`  Working dir: ${projectDir}`);
+    if (signals.length > 0) {
+      output.add(`  Weak signals: ${signals.join(', ')}`);
+    }
+    output.addQuestion(
+      `Git root is at \`${gitRoot}\` (${depth} levels up), which doesn't look like a monorepo. May have been created accidentally.`,
+      'single_select',
+      [
+        '"It\'s correct" \u2014 continue normally',
+        '"Initialise here instead" \u2014 run `git init` here (warn ancestor .git still exists)',
+        '"Investigate" \u2014 list git root contents and recent commits',
+      ],
+    );
+  }
+}
+
+function detectMonorepo(gitRoot) {
+  const signals = [];
+
+  // Check workspaces in package.json
+  const pkg = readJson(join(gitRoot, 'package.json'));
+  if (pkg && pkg.workspaces) {
+    signals.push('package.json has \'workspaces\' field');
+  }
+
+  // Check marker files
+  for (const marker of config.monorepo.markers) {
+    if (existsSync(join(gitRoot, marker))) {
+      signals.push(`${marker} exists`);
+    }
+  }
+
+  // Check common monorepo directories
+  for (const dir of config.monorepo.dirs) {
+    if (existsSync(join(gitRoot, dir))) {
+      signals.push(`'${dir}/' directory exists at git root`);
+    }
+  }
+
+  // Count package.json files (crude monorepo signal)
+  const pkgCount = git('ls-files --cached --others --exclude-standard -- "*/package.json" "package.json"', gitRoot);
+  if (pkgCount) {
+    const count = pkgCount.split('\n').filter(Boolean).length;
+    if (count > 2) signals.push(`${count} package.json files found`);
+  }
+
+  // Count CLAUDE.md files
+  const claudeCount = git('ls-files --cached -- "*/CLAUDE.md" "CLAUDE.md"', gitRoot);
+  if (claudeCount) {
+    const count = claudeCount.split('\n').filter(Boolean).length;
+    if (count > 1) signals.push(`${count} CLAUDE.md files found (per-package setup)`);
+  }
+
+  return signals;
+}
+
+module.exports = { checkGit };

package/hooks/lib/output.cjs

@@ -0,0 +1,47 @@
+'use strict';
+
+class OutputBuilder {
+  constructor() {
+    this.parts = [];
+    this.signals = [];
+    this.score = 0;
+  }
+
+  add(line) {
+    this.parts.push(line);
+  }
+
+  blank() {
+    this.parts.push('');
+  }
+
+  addStaleness(message, weight = 1) {
+    this.signals.push(`\u26A0 ${message}`);
+    this.score += weight;
+  }
+
+  addQuestion(question, type, options, priority) {
+    this.blank();
+    if (priority === 'low') {
+      this.add('Use AskUserQuestion (low priority, don\'t block):');
+    } else {
+      this.add('Use AskUserQuestion to prompt:');
+    }
+    this.add(`  Question: "${question}"`);
+    this.add(`  Type: ${type}`);
+    this.add('  Options:');
+    options.forEach((opt, i) => this.add(`    ${i + 1}. ${opt}`));
+    this.blank();
+  }
+
+  toJson(hookEvent = 'SessionStart') {
+    return JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: hookEvent,
+        additionalContext: this.parts.join('\n'),
+      },
+    });
+  }
+}
+
+module.exports = { OutputBuilder };

package/hooks/lib/staleness.cjs

@@ -0,0 +1,154 @@
+'use strict';
+
+const { existsSync } = require('fs');
+const { join } = require('path');
+const config = require('./config.cjs');
+const { fileMtime, git, readJson, readText, getDirectories } = require('./utils.cjs');
+
+/**
+ * Evaluate all staleness signals for CLAUDE.md.
+ * Mutates output.addStaleness() with weighted signals.
+ */
+function checkStaleness(projectDir, claudeMdPath, gitRoot, output) {
+  const now = Math.floor(Date.now() / 1000);
+  const mdMtime = fileMtime(claudeMdPath);
+  const mdAgeDays = Math.floor((now - mdMtime) / 86400);
+
+  checkAge(mdAgeDays, output);
+  checkDirectoryDrift(projectDir, claudeMdPath, output);
+  checkPackageJson(projectDir, claudeMdPath, mdMtime, output);
+  checkPythonDeps(projectDir, mdMtime, output);
+  checkConfigFiles(projectDir, mdMtime, output);
+  checkGitActivity(projectDir, gitRoot, mdMtime, output);
+  checkLockFiles(projectDir, mdMtime, output);
+}
+
+// ─── Individual checks ─────────────────────────────────────────────────
+
+function checkAge(ageDays, output) {
+  const { warn, critical } = config.staleness.age;
+  if (ageDays > critical) {
+    output.addStaleness(`CLAUDE.md last modified ${ageDays} days ago`, 2);
+  } else if (ageDays > warn) {
+    output.addStaleness(`CLAUDE.md last modified ${ageDays} days ago`, 1);
+  }
+}
+
+function checkDirectoryDrift(projectDir, claudeMdPath, output) {
+  const dirs = getDirectories(projectDir);
+  if (dirs.length === 0) return;
+
+  const claudeMd = readText(claudeMdPath);
+  if (!claudeMd) return;
+
+  const mdLower = claudeMd.toLowerCase();
+  const missing = dirs.filter(d => !mdLower.includes(d.toLowerCase()));
+
+  if (missing.length > config.staleness.missingDirs.many) {
+    output.addStaleness(`Directories not in CLAUDE.md: ${missing.join(' ')}`, 2);
+  } else if (missing.length > config.staleness.missingDirs.few) {
+    output.addStaleness(`Directories not in CLAUDE.md: ${missing.join(' ')}`, 1);
+  }
+}
+
+function checkPackageJson(projectDir, claudeMdPath, mdMtime, output) {
+  const pkgPath = join(projectDir, 'package.json');
+  if (!existsSync(pkgPath)) return;
+
+  const pkgMtime = fileMtime(pkgPath);
+  if (pkgMtime > mdMtime) {
+    const delta = Math.floor((pkgMtime - mdMtime) / 86400);
+    output.addStaleness(`package.json modified ${delta} day(s) after CLAUDE.md`, 1);
+  }
+
+  const pkg = readJson(pkgPath);
+  if (!pkg) return;
+
+  const depCount = Object.keys(pkg.dependencies || {}).length
+    + Object.keys(pkg.devDependencies || {}).length;
+
+  const claudeMd = readText(claudeMdPath) || '';
+  const documented = claudeMd.match(/(\d+)\s*(dependencies|deps)/i);
+  if (documented) {
+    const docCount = parseInt(documented[1], 10);
+    const drift = Math.abs(depCount - docCount);
+    if (drift > config.staleness.depDrift.major) {
+      output.addStaleness(`Dep count drift: CLAUDE.md ~${docCount}, actual ${depCount} (\u0394${depCount - docCount})`, 2);
+    } else if (drift > config.staleness.depDrift.minor) {
+      output.addStaleness(`Dep count drift: CLAUDE.md ~${docCount}, actual ${depCount}`, 1);
+    }
+  }
+
+  // Check for undocumented production deps
+  const prodDeps = Object.keys(pkg.dependencies || {});
+  const mdLower = claudeMd.toLowerCase();
+  const undocumented = prodDeps.filter(d => !mdLower.includes(d.toLowerCase()));
+  if (undocumented.length > config.staleness.undocumentedDeps) {
+    output.addStaleness(
+      `${undocumented.length} production deps not in CLAUDE.md (e.g. ${undocumented.slice(0, 5).join(', ')})`,
+      2,
+    );
+  }
+}
+
+function checkPythonDeps(projectDir, mdMtime, output) {
+  for (const file of config.pythonFiles) {
+    const path = join(projectDir, file);
+    if (!existsSync(path)) continue;
+    if (fileMtime(path) > mdMtime) {
+      output.addStaleness(`${file} modified after CLAUDE.md`, 1);
+    }
+  }
+}
+
+function checkConfigFiles(projectDir, mdMtime, output) {
+  for (const file of config.configFiles) {
+    const path = join(projectDir, file);
+    if (!existsSync(path)) continue;
+    if (fileMtime(path) > mdMtime) {
+      output.addStaleness(`${file} modified after CLAUDE.md`, 1);
+    }
+  }
+}
+
+function checkGitActivity(projectDir, gitRoot, mdMtime, output) {
+  if (!gitRoot) return;
+
+  // Convert epoch to ISO date for git --since
+  const mdDate = new Date(mdMtime * 1000).toISOString();
+
+  const commitsSince = parseInt(
+    git(`rev-list --count --since="${mdDate}" HEAD`, projectDir) || '0',
+    10,
+  );
+
+  if (commitsSince > config.staleness.commits.critical) {
+    output.addStaleness(`${commitsSince} commits since CLAUDE.md updated`, 2);
+  } else if (commitsSince > config.staleness.commits.warn) {
+    output.addStaleness(`${commitsSince} commits since CLAUDE.md updated`, 1);
+  }
+
+  // Check for top-level file churn
+  const changed = git('diff --name-only --diff-filter=AD HEAD~20..HEAD', projectDir);
+  if (changed) {
+    const topLevel = changed.split('\n')
+      .filter(f => f && !f.includes('/') && !f.startsWith('.'));
+    if (topLevel.length > config.staleness.topLevelFiles) {
+      output.addStaleness(`${topLevel.length} top-level files added/removed recently`, 1);
+    }
+  }
+}
+
+function checkLockFiles(projectDir, mdMtime, output) {
+  for (const file of config.lockFiles) {
+    const path = join(projectDir, file);
+    if (!existsSync(path)) continue;
+    const delta = Math.floor((fileMtime(path) - mdMtime) / 86400);
+    if (delta > config.staleness.lockFileDays) {
+      output.addStaleness(`${file} is ${delta} days newer than CLAUDE.md`, 1);
+      return; // Only flag once
+    }
+  }
+}
+
+module.exports = { checkStaleness };

package/hooks/lib/state.cjs

@@ -0,0 +1,52 @@
+'use strict';
+
+const { mkdirSync, writeFileSync, readFileSync, unlinkSync, existsSync } = require('fs');
+const { join } = require('path');
+const { createHash } = require('crypto');
+const { homedir } = require('os');
+
+const STATE_DIR = join(homedir(), '.claude', 'session-guard');
+
+function ensureDir() {
+  mkdirSync(STATE_DIR, { recursive: true });
+}
+
+function projectKey(projectDir) {
+  return createHash('md5').update(projectDir).digest('hex');
+}
+
+function statePath(projectDir) {
+  return join(STATE_DIR, `${projectKey(projectDir)}.json`);
+}
+
+function save(projectDir, data) {
+  ensureDir();
+  writeFileSync(statePath(projectDir), JSON.stringify({
+    ...data,
+    projectDir,
+    timestamp: Date.now(),
+  }, null, 2));
+}
+
+function load(projectDir) {
+  const path = statePath(projectDir);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function clear(projectDir) {
+  try { unlinkSync(statePath(projectDir)); } catch { /* noop */ }
+}
+
+/** Dedup: true if check ran within the last `seconds`. */
+function isRecentlyChecked(projectDir, seconds = 5) {
+  const data = load(projectDir);
+  if (!data) return false;
+  return (Date.now() - data.timestamp) < seconds * 1000;
+}
+
+module.exports = { save, load, clear, isRecentlyChecked };

package/hooks/lib/task-checks.cjs

@@ -0,0 +1,53 @@
+'use strict';
+
+const { existsSync } = require('fs');
+const { join, basename } = require('path');
+const { homedir } = require('os');
+const config = require('./config.cjs');
+const { readJson, git } = require('./utils.cjs');
+
+/**
+ * Check if a persistent Task List ID is configured.
+ */
+function checkTaskList(projectDir, gitRoot, output) {
+  if (isTaskListConfigured(projectDir)) return;
+  if (!gitRoot) return;
+
+  const commitCount = parseInt(git('rev-list --count HEAD', projectDir) || '0', 10);
+  const fileOutput = git('ls-files', projectDir);
+  const fileCount = fileOutput ? fileOutput.split('\n').filter(Boolean).length : 0;
+
+  if (commitCount <= config.taskList.minCommits && fileCount <= config.taskList.minFiles) return;
+
+  const repoName = basename(gitRoot);
+  output.add('[SESSION GUARD] \u2139\uFE0F  No persistent Task List ID configured.');
+  output.add(`  Project: ${commitCount} commits, ${fileCount} tracked files.`);
+  output.addQuestion(
+    'No persistent Task List ID configured. For a project this size, tasks won\'t survive across sessions. Add one?',
+    'single_select',
+    [
+      `"Yes" \u2014 add {"env": {"CLAUDE_CODE_TASK_LIST_ID": "${repoName}"}} to .claude/settings.json`,
+      '"Skip" \u2014 continue without persistent tasks',
+    ],
+    'low',
+  );
+}
+
+function isTaskListConfigured(projectDir) {
+  if (process.env.CLAUDE_CODE_TASK_LIST_ID) return true;
+
+  const candidates = [
+    join(projectDir, '.claude', 'settings.json'),
+    join(homedir(), '.claude', 'settings.json'),
+  ];
+
+  for (const path of candidates) {
+    if (!existsSync(path)) continue;
+    const settings = readJson(path);
+    if (settings?.env?.CLAUDE_CODE_TASK_LIST_ID) return true;
+  }
+
+  return false;
+}
+
+module.exports = { checkTaskList };

package/hooks/lib/utils.cjs

@@ -0,0 +1,90 @@
+'use strict';
+
+const { execSync } = require('child_process');
+const { statSync, existsSync, readFileSync, readdirSync } = require('fs');
+const { join } = require('path');
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', '__pycache__', '.venv', 'venv',
+  'dist', 'build', '.next', '.nuxt', 'coverage', '.claude',
+  '.idea', '.vscode', 'target', '.cache', '.turbo',
+]);
+
+/** Epoch seconds of file mtime — falls back to now on error. */
+function fileMtime(filePath) {
+  try {
+    return Math.floor(statSync(filePath).mtimeMs / 1000);
+  } catch {
+    return Math.floor(Date.now() / 1000);
+  }
+}
+
+/** Run a git command, return trimmed stdout or null on failure. */
+function git(args, cwd) {
+  try {
+    return execSync(`git ${args}`, {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 10000,
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/** Parse a JSON file, return null on failure. */
+function readJson(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Read file as string, return null on failure. */
+function readText(filePath) {
+  try {
+    return readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * List directories up to maxDepth (replaces `tree -L 2 -d`).
+ * Returns flat array of relative dir names.
+ */
+function getDirectories(dir, maxDepth = 2, _depth = 0) {
+  if (_depth >= maxDepth) return [];
+  const dirs = [];
+  try {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith('.') || IGNORE_DIRS.has(entry.name)) continue;
+      dirs.push(entry.name);
+      if (_depth + 1 < maxDepth) {
+        for (const sub of getDirectories(join(dir, entry.name), maxDepth, _depth + 1)) {
+          dirs.push(`${entry.name}/${sub}`);
+        }
+      }
+    }
+  } catch { /* directory not readable */ }
+  return dirs;
+}
+
+/**
+ * Count files matching a glob pattern in a directory (non-recursive).
+ */
+function countFiles(dir, pattern) {
+  try {
+    return readdirSync(dir).filter(f => {
+      if (pattern) return f.match(pattern);
+      return true;
+    }).length;
+  } catch {
+    return 0;
+  }
+}
+
+module.exports = { fileMtime, git, readJson, readText, getDirectories, countFiles, existsSync };

package/hooks/session-guard.cjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Session Guard — Claude Code project health validation
+ *
+ * Replaces the shell-based session-guard.sh + session-guard-prompt.sh with a
+ * single Node.js entry point using subcommand dispatch (modelled on claude-mem's
+ * worker-service.cjs pattern).
+ *
+ * Subcommands:
+ *   check   — SessionStart: validate git, CLAUDE.md, tasks, staleness
+ *   remind  — UserPromptSubmit: re-emit pending context on first prompt
+ *
+ * Usage:
+ *   node session-guard.js check
+ *   node session-guard.js remind
+ */
+
+const { existsSync } = require('fs');
+const { join } = require('path');
+
+const config = require('./lib/config.cjs');
+const state = require('./lib/state.cjs');
+const { OutputBuilder } = require('./lib/output.cjs');
+const { getBanner, BANNER_MARKER } = require('./lib/banner.cjs');
+const { checkGit } = require('./lib/git-checks.cjs');
+const { checkTaskList } = require('./lib/task-checks.cjs');
+const { checkStaleness } = require('./lib/staleness.cjs');
+
+const PROJECT_DIR = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const CLAUDE_MD = join(PROJECT_DIR, 'CLAUDE.md');
+
+// ─── check ─────────────────────────────────────────────────────────────
+// Runs at SessionStart. Validates project health and emits context.
+
+function check() {
+  // Dedup: skip if recently checked (handles dual global+project registration)
+  if (state.isRecentlyChecked(PROJECT_DIR)) {
+    console.log(JSON.stringify({}));
+    return;
+  }
+
+  const output = new OutputBuilder();
+
+  // Banner — shown once per session at start
+  output.add(getBanner());
+  output.blank();
+
+  // 0) Git repository validation
+  const { gitRoot } = checkGit(PROJECT_DIR, output);
+
+  // 1) CLAUDE.md existence
+  if (!existsSync(CLAUDE_MD)) {
+    output.add('[SESSION GUARD] \u26A0\uFE0F  No CLAUDE.md found in project root.');
+    output.addQuestion(
+      'No CLAUDE.md found. Want me to set up this project for Claude Code?',
+      'single_select',
+      [
+        '"Initialise" \u2014 run `/init` to scaffold CLAUDE.md',
+        '"Skip" \u2014 continue without one',
+      ],
+    );
+    emit(output);
+    return;
+  }
+
+  output.add(`[SESSION GUARD] \u2705 CLAUDE.md found in: ${PROJECT_DIR}`);
+
+  // 2) Task List ID
+  checkTaskList(PROJECT_DIR, gitRoot, output);
+
+  // 3) Staleness evaluation
+  checkStaleness(PROJECT_DIR, CLAUDE_MD, gitRoot, output);
+
+  // 4) Staleness summary
+  if (output.score >= config.staleness.threshold) {
+    output.blank();
+    output.add(`[SESSION GUARD] \u26A0\uFE0F  CLAUDE.md appears STALE (score: ${output.score}/${config.staleness.threshold})`);
+    output.blank();
+    output.add('Signals:');
+    output.signals.forEach(sig => output.add(`  ${sig}`));
+    output.addQuestion(
+      `CLAUDE.md appears out of date (${output.signals.length} signals detected). What would you like to do?`,
+      'single_select',
+      [
+        '"Update it" \u2014 review project structure, deps, recent changes and update CLAUDE.md (preserve user-written notes)',
+        '"Show signals" \u2014 list what\'s drifted before deciding',
+        '"Skip" \u2014 continue with current CLAUDE.md',
+      ],
+    );
+  } else if (output.signals.length > 0) {
+    output.blank();
+    output.add(`[SESSION GUARD] \u2139\uFE0F  Minor drift (score: ${output.score}/${config.staleness.threshold}) \u2014 not flagging:`);
+    output.signals.forEach(sig => output.add(`  ${sig}`));
+  }
+
+  emit(output);
+}
+
+// ─── remind ────────────────────────────────────────────────────────────
+// Runs at UserPromptSubmit. Re-emits pending context from check, once.
+
+function remind() {
+  const pending = state.load(PROJECT_DIR);
+
+  if (!pending || !pending.context) {
+    console.log(JSON.stringify({}));
+    return;
+  }
+
+  state.clear(PROJECT_DIR);
+
+  // Skip re-emit if no warnings were found
+  if (!pending.context.includes('\u26A0\uFE0F') && !pending.context.includes('\u2139\uFE0F')) {
+    console.log(JSON.stringify({}));
+    return;
+  }
+
+  // Strip banner from re-emission (already shown at SessionStart)
+  const lines = pending.context.split('\n');
+  const guardIdx = lines.findIndex(l => l.startsWith('[SESSION GUARD]'));
+  const body = guardIdx >= 0 ? lines.slice(guardIdx).join('\n') : pending.context;
+
+  const wrapped = [
+    '[SESSION GUARD \u2014 FIRST PROMPT REMINDER]',
+    'The following was detected at session start. Act on these items NOW using',
+    'AskUserQuestion BEFORE proceeding with the user\'s request.',
+    '',
+    body,
+  ].join('\n');
+
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext: wrapped,
+    },
+  }));
+}
+
+// ─── helpers ───────────────────────────────────────────────────────────
+
+function emit(output) {
+  console.log(output.toJson());
+  state.save(PROJECT_DIR, {
+    context: output.parts.join('\n'),
+    score: output.score,
+    signals: output.signals,
+  });
+}
+
+// ─── dispatch ──────────────────────────────────────────────────────────
+
+const command = process.argv[2];
+
+switch (command) {
+  case 'check':
+    check();
+    break;
+  case 'remind':
+    remind();
+    break;
+  default:
+    console.error(`Session Guard v${config.version}`);
+    console.error('Usage: node session-guard.js <check|remind>');
+    process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slamb2k/mad-skills",
-  "version": "2.0.11",
+  "version": "2.0.13",
   "description": "Claude Code skills collection — planning, development and governance tools",
   "type": "module",
   "repository": {

package/skills/manifest.json

@@ -1,5 +1,5 @@
 {
-  "generated": "2026-03-08T22:56:33.887Z",
+  "generated": "2026-03-09T14:07:03.881Z",
   "count": 8,
   "skills": [
     {

package/hooks/session-guard-prompt.sh

@@ -1,54 +0,0 @@
-#!/usr/bin/env bash
-# session-guard-prompt.sh — UserPromptSubmit companion hook for session-guard
-#
-# Checks if session-guard.sh left a pending context file from SessionStart.
-# If found, re-emits the context as additionalContext on the first user prompt,
-# then deletes the flag file so it only fires once.
-#
-# This works around the known limitation where SessionStart hook output is
-# silently injected and may not surface until after the first prompt is
-# already processed (see anthropics/claude-code#10808).
-#
-# Install globally in ~/.claude/settings.json:
-#   "command": "\"$HOME\"/.claude/hooks/session-guard-prompt.sh"
-#
-# Or per-project in .claude/settings.json:
-#   "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-guard-prompt.sh"
-
-set -uo pipefail
-
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
-PENDING_DIR="${TMPDIR:-/tmp}/claude-session-guard"
-GUARD_KEY=$(echo "$PROJECT_DIR" | md5sum 2>/dev/null | cut -d' ' -f1 || echo "default")
-PENDING_FILE="$PENDING_DIR/$GUARD_KEY.pending"
-
-# No pending file — fast exit
-if [[ ! -f "$PENDING_FILE" ]]; then
-  jq -n '{}'
-  exit 0
-fi
-
-CONTEXT=$(cat "$PENDING_FILE")
-rm -f "$PENDING_FILE"
-
-# Also clean up the dedup lock from session-guard.sh
-rm -f "$PENDING_DIR/$GUARD_KEY.lock"
-
-# Skip re-emit if session-guard found no issues (just the ✅ line, no warnings)
-if [[ $(echo "$CONTEXT" | grep -c '⚠️\|ℹ️') -eq 0 ]]; then
-  jq -n '{}'
-  exit 0
-fi
-
-# Output context as plain stdout to avoid the cosmetic "error" label
-# that Claude Code renders when additionalContext is in the JSON output.
-# Plain stdout is picked up as hook output without the error severity.
-cat <<EOF
-[SESSION GUARD — FIRST PROMPT REMINDER]
-The following was detected at session start. Act on these items NOW using
-AskUserQuestion BEFORE proceeding with the user's request.
-
-$CONTEXT
-EOF
-
-exit 0

package/hooks/session-guard.sh

@@ -1,401 +0,0 @@
-#!/usr/bin/env bash
-# session-guard.sh — Claude Code SessionStart hook
-# Validates Git repo, CLAUDE.md existence/freshness, Task List ID config,
-# and checks for staleness.
-#
-# All user-facing questions instruct Claude to use the AskUserQuestion tool.
-#
-# Install globally in ~/.claude/settings.json:
-#   "command": "\"$HOME\"/.claude/hooks/session-guard.sh"
-#
-# Or per-project in .claude/settings.json:
-#   "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-guard.sh"
-#
-# TIMING NOTE: SessionStart hook output is silently injected and only surfaces
-# on the user's first prompt. Pair with session-guard-prompt.sh on
-# UserPromptSubmit for immediate feedback (see companion hook).
-
-# NOTE: We intentionally avoid `set -e` here. Many commands (grep, git, find,
-# jq, stat) return non-zero for perfectly normal reasons (no matches, not a
-# repo, missing files). Letting them fail gracefully is simpler and more
-# reliable than wrapping every line in `|| true`.
-set -uo pipefail
-
-# ---------------------------------------------------------------------------
-# Config
-# ---------------------------------------------------------------------------
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
-CLAUDE_MD="$PROJECT_DIR/CLAUDE.md"
-NOW=$(date +%s)
-STALENESS_THRESHOLD=3   # Accumulated score >= this triggers user prompt
-PENDING_DIR="${TMPDIR:-/tmp}/claude-session-guard"
-
-# ---------------------------------------------------------------------------
-# State
-# ---------------------------------------------------------------------------
-EARLY_CONTEXT_PARTS=()
-STALENESS_SIGNALS=()
-STALENESS_SCORE=0
-
-add_staleness() {
-  local msg="$1"
-  local weight="${2:-1}"
-  STALENESS_SIGNALS+=("⚠ $msg")
-  STALENESS_SCORE=$((STALENESS_SCORE + weight))
-}
-
-# Portable stat wrapper: returns mtime as epoch seconds
-file_mtime() {
-  stat -c %Y "$1" 2>/dev/null || stat -f %m "$1" 2>/dev/null || echo "$NOW"
-}
-
-# ---------------------------------------------------------------------------
-# Dedup: prevent double-firing if configured at both global and project level
-# ---------------------------------------------------------------------------
-mkdir -p "$PENDING_DIR"
-GUARD_KEY=$(echo "$PROJECT_DIR" | md5sum 2>/dev/null | cut -d' ' -f1 || echo "default")
-LOCK_FILE="$PENDING_DIR/$GUARD_KEY.lock"
-
-if [[ -f "$LOCK_FILE" ]]; then
-  LOCK_AGE=$(( NOW - $(file_mtime "$LOCK_FILE") ))
-  if (( LOCK_AGE < 5 )); then
-    jq -n '{}'
-    exit 0
-  fi
-fi
-touch "$LOCK_FILE"
-
-# ---------------------------------------------------------------------------
-# 0) Git repository check
-# ---------------------------------------------------------------------------
-GIT_ROOT=""
-
-if command -v git &>/dev/null; then
-  GIT_ROOT=$(git -C "$PROJECT_DIR" rev-parse --show-toplevel 2>/dev/null) || true
-
-  if [[ -z "$GIT_ROOT" ]]; then
-    EARLY_CONTEXT_PARTS+=("[SESSION GUARD] ⚠️  This directory is NOT tracked by Git.")
-    EARLY_CONTEXT_PARTS+=("")
-    EARLY_CONTEXT_PARTS+=("Use AskUserQuestion to prompt:")
-    EARLY_CONTEXT_PARTS+=("  Question: \"This directory isn't inside a Git repository. What would you like to do?\"")
-    EARLY_CONTEXT_PARTS+=("  Type: single_select")
-    EARLY_CONTEXT_PARTS+=("  Options:")
-    EARLY_CONTEXT_PARTS+=("    1. \"Initialise Git\" — run \`git init\` and suggest creating .gitignore")
-    EARLY_CONTEXT_PARTS+=("    2. \"Skip\" — continue without version control")
-    EARLY_CONTEXT_PARTS+=("")
-
-  elif [[ "$GIT_ROOT" != "$PROJECT_DIR" ]]; then
-    DEPTH=0
-    CHECK_DIR="$PROJECT_DIR"
-    while [[ "$CHECK_DIR" != "$GIT_ROOT" && "$CHECK_DIR" != "/" ]]; do
-      CHECK_DIR=$(dirname "$CHECK_DIR")
-      DEPTH=$((DEPTH + 1))
-    done
-
-    MONOREPO_SIGNALS=()
-
-    if [[ -f "$GIT_ROOT/package.json" ]] && command -v jq &>/dev/null; then
-      jq -e '.workspaces // empty' "$GIT_ROOT/package.json" &>/dev/null && \
-        MONOREPO_SIGNALS+=("package.json has 'workspaces' field")
-    fi
-    [[ -f "$GIT_ROOT/pnpm-workspace.yaml" ]] && MONOREPO_SIGNALS+=("pnpm-workspace.yaml exists")
-    [[ -f "$GIT_ROOT/lerna.json" ]]          && MONOREPO_SIGNALS+=("lerna.json exists")
-    [[ -f "$GIT_ROOT/nx.json" ]]             && MONOREPO_SIGNALS+=("nx.json exists")
-    [[ -f "$GIT_ROOT/turbo.json" ]]          && MONOREPO_SIGNALS+=("turbo.json exists")
-    [[ -f "$GIT_ROOT/rush.json" ]]           && MONOREPO_SIGNALS+=("rush.json exists")
-
-    for d in packages apps services libs modules projects; do
-      [[ -d "$GIT_ROOT/$d" ]] && MONOREPO_SIGNALS+=("'$d/' directory exists at git root")
-    done
-
-    PKG_COUNT=$(find "$GIT_ROOT" -maxdepth 3 -name "package.json" -not -path "*/node_modules/*" 2>/dev/null | wc -l | tr -d ' ')
-    (( PKG_COUNT > 2 )) && MONOREPO_SIGNALS+=("${PKG_COUNT} package.json files found")
-
-    CLAUDE_MD_COUNT=$(find "$GIT_ROOT" -maxdepth 3 -name "CLAUDE.md" 2>/dev/null | wc -l | tr -d ' ')
-    (( CLAUDE_MD_COUNT > 1 )) && MONOREPO_SIGNALS+=("${CLAUDE_MD_COUNT} CLAUDE.md files found (per-package setup)")
-
-    RELATIVE_PATH="${PROJECT_DIR#"$GIT_ROOT/"}"
-
-    if (( ${#MONOREPO_SIGNALS[@]} >= 2 )); then
-      EARLY_CONTEXT_PARTS+=("[SESSION GUARD] ℹ️  Git root is ${DEPTH} level(s) above CWD.")
-      EARLY_CONTEXT_PARTS+=("  Git root:    $GIT_ROOT")
-      EARLY_CONTEXT_PARTS+=("  Working dir: $PROJECT_DIR")
-      EARLY_CONTEXT_PARTS+=("  Monorepo signals: ${MONOREPO_SIGNALS[*]}")
-      EARLY_CONTEXT_PARTS+=("")
-      EARLY_CONTEXT_PARTS+=("Use AskUserQuestion (low priority, don't block):")
-      EARLY_CONTEXT_PARTS+=("  Question: \"Git root is at \`$GIT_ROOT\` (monorepo). Working in \`${RELATIVE_PATH}\`. Correct context?\"")
-      EARLY_CONTEXT_PARTS+=("  Type: single_select")
-      EARLY_CONTEXT_PARTS+=("  Options:")
-      EARLY_CONTEXT_PARTS+=("    1. \"Yes, correct package\"")
-      EARLY_CONTEXT_PARTS+=("    2. \"No, switch to repo root\"")
-      EARLY_CONTEXT_PARTS+=("")
-
-    else
-      GIT_ROOT_FILE_COUNT=$(find "$GIT_ROOT" -maxdepth 1 -not -name '.*' 2>/dev/null | wc -l | tr -d ' ')
-
-      EARLY_CONTEXT_PARTS+=("[SESSION GUARD] ⚠️  Git root is ${DEPTH} level(s) above CWD — does NOT look like a monorepo.")
-      EARLY_CONTEXT_PARTS+=("  Git root:    $GIT_ROOT (${GIT_ROOT_FILE_COUNT} files)")
-      EARLY_CONTEXT_PARTS+=("  Working dir: $PROJECT_DIR")
-      if (( ${#MONOREPO_SIGNALS[@]} > 0 )); then
-        EARLY_CONTEXT_PARTS+=("  Weak signals: ${MONOREPO_SIGNALS[*]}")
-      fi
-      EARLY_CONTEXT_PARTS+=("")
-      EARLY_CONTEXT_PARTS+=("Use AskUserQuestion to resolve:")
-      EARLY_CONTEXT_PARTS+=("  Question: \"Git root is at \`$GIT_ROOT\` (${DEPTH} levels up), which doesn't look like a monorepo. May have been created accidentally.\"")
-      EARLY_CONTEXT_PARTS+=("  Type: single_select")
-      EARLY_CONTEXT_PARTS+=("  Options:")
-      EARLY_CONTEXT_PARTS+=("    1. \"It's correct\" — continue normally")
-      EARLY_CONTEXT_PARTS+=("    2. \"Initialise here instead\" — run \`git init\` here (warn ancestor .git still exists)")
-      EARLY_CONTEXT_PARTS+=("    3. \"Investigate\" — list git root contents and recent commits")
-      EARLY_CONTEXT_PARTS+=("")
-    fi
-  fi
-fi
-
-# ---------------------------------------------------------------------------
-# 1) CLAUDE.md existence check
-# ---------------------------------------------------------------------------
-if [[ ! -f "$CLAUDE_MD" ]]; then
-  EARLY_CONTEXT_PARTS+=("[SESSION GUARD] ⚠️  No CLAUDE.md found in project root.")
-  EARLY_CONTEXT_PARTS+=("")
-  EARLY_CONTEXT_PARTS+=("Use AskUserQuestion to prompt:")
-  EARLY_CONTEXT_PARTS+=("  Question: \"No CLAUDE.md found. Want me to set up this project for Claude Code?\"")
-  EARLY_CONTEXT_PARTS+=("  Type: single_select")
-  EARLY_CONTEXT_PARTS+=("  Options:")
-  EARLY_CONTEXT_PARTS+=("    1. \"Initialise\" — run \`/init\` to scaffold CLAUDE.md")
-  EARLY_CONTEXT_PARTS+=("    2. \"Skip\" — continue without one")
-  EARLY_CONTEXT_PARTS+=("")
-
-  # Emit and write pending flag, then exit early
-  CONTEXT=$(printf '%s\n' "${EARLY_CONTEXT_PARTS[@]}")
-  jq -n --arg ctx "$CONTEXT" '{
-    hookSpecificOutput: {
-      hookEventName: "SessionStart",
-      additionalContext: $ctx
-    }
-  }'
-  PENDING_FILE="$PENDING_DIR/$GUARD_KEY.pending"
-  echo "$CONTEXT" > "$PENDING_FILE"
-  exit 0
-fi
-
-# ---------------------------------------------------------------------------
-# 2) Task List ID check
-# ---------------------------------------------------------------------------
-TASK_LIST_CONFIGURED=false
-SETTINGS_FILE="$PROJECT_DIR/.claude/settings.json"
-
-[[ -n "${CLAUDE_CODE_TASK_LIST_ID:-}" ]] && TASK_LIST_CONFIGURED=true
-
-if [[ "$TASK_LIST_CONFIGURED" == false ]] && command -v jq &>/dev/null; then
-  if [[ -f "$SETTINGS_FILE" ]]; then
-    TASK_ID=$(jq -r '.env.CLAUDE_CODE_TASK_LIST_ID // empty' "$SETTINGS_FILE" 2>/dev/null) || true
-    [[ -n "$TASK_ID" ]] && TASK_LIST_CONFIGURED=true
-  fi
-fi
-
-if [[ "$TASK_LIST_CONFIGURED" == false && -n "$GIT_ROOT" ]]; then
-  COMMIT_COUNT=$(git -C "$PROJECT_DIR" rev-list --count HEAD 2>/dev/null) || COMMIT_COUNT=0
-  FILE_COUNT=$(git -C "$PROJECT_DIR" ls-files 2>/dev/null | wc -l | tr -d ' ') || FILE_COUNT=0
-
-  if (( COMMIT_COUNT > 20 || FILE_COUNT > 30 )); then
-    REPO_NAME=$(basename "$GIT_ROOT")
-    EARLY_CONTEXT_PARTS+=("[SESSION GUARD] ℹ️  No persistent Task List ID configured.")
-    EARLY_CONTEXT_PARTS+=("  Project: ${COMMIT_COUNT} commits, ${FILE_COUNT} tracked files.")
-    EARLY_CONTEXT_PARTS+=("")
-    EARLY_CONTEXT_PARTS+=("Use AskUserQuestion (low priority, don't block):")
-    EARLY_CONTEXT_PARTS+=("  Question: \"No persistent Task List ID configured. For a project this size, tasks won't survive across sessions. Add one?\"")
-    EARLY_CONTEXT_PARTS+=("  Type: single_select")
-    EARLY_CONTEXT_PARTS+=("  Options:")
-    EARLY_CONTEXT_PARTS+=("    1. \"Yes\" — add {\"env\": {\"CLAUDE_CODE_TASK_LIST_ID\": \"${REPO_NAME}\"}} to .claude/settings.json")
-    EARLY_CONTEXT_PARTS+=("    2. \"Skip\" — continue without persistent tasks")
-    EARLY_CONTEXT_PARTS+=("")
-  fi
-fi
-
-# ---------------------------------------------------------------------------
-# 3) Staleness evaluation
-# ---------------------------------------------------------------------------
-CLAUDE_MD_MTIME=$(file_mtime "$CLAUDE_MD")
-CLAUDE_MD_AGE_DAYS=$(( (NOW - CLAUDE_MD_MTIME) / 86400 ))
-
-# --- Age-based --------------------------------------------------------------
-if (( CLAUDE_MD_AGE_DAYS > 14 )); then
-  add_staleness "CLAUDE.md last modified ${CLAUDE_MD_AGE_DAYS} days ago" 2
-elif (( CLAUDE_MD_AGE_DAYS > 7 )); then
-  add_staleness "CLAUDE.md last modified ${CLAUDE_MD_AGE_DAYS} days ago" 1
-fi
-
-# --- Directory structure drift ----------------------------------------------
-if command -v tree &>/dev/null; then
-  CURRENT_TREE=$(tree -L 2 -d -I 'node_modules|.git|__pycache__|.venv|venv|dist|build|.next|.nuxt|coverage|.claude' --noreport "$PROJECT_DIR" 2>/dev/null) || true
-  if [[ -n "$CURRENT_TREE" ]]; then
-    TREE_DIRS=$(echo "$CURRENT_TREE" | tail -n +2 \
-      | sed 's/[│├└─┬┤┼┐┘┌┏┗┓┛]//g; s/[|`]//g; s/--*//g' \
-      | sed 's/^[[:space:]]*//' | { grep -v '^$' || true; } | sort -u)
-    MISSING_DIRS=()
-    while IFS= read -r dir; do
-      [[ -z "$dir" ]] && continue
-      grep -qi "$dir" "$CLAUDE_MD" 2>/dev/null || MISSING_DIRS+=("$dir")
-    done <<< "$TREE_DIRS"
-    if (( ${#MISSING_DIRS[@]} > 2 )); then
-      add_staleness "Directories not in CLAUDE.md: ${MISSING_DIRS[*]}" 2
-    elif (( ${#MISSING_DIRS[@]} > 0 )); then
-      add_staleness "Directories not in CLAUDE.md: ${MISSING_DIRS[*]}" 1
-    fi
-  fi
-fi
-
-# --- package.json drift -----------------------------------------------------
-if [[ -f "$PROJECT_DIR/package.json" ]]; then
-  PKG_MTIME=$(file_mtime "$PROJECT_DIR/package.json")
-
-  if (( PKG_MTIME > CLAUDE_MD_MTIME )); then
-    PKG_DELTA=$(( (PKG_MTIME - CLAUDE_MD_MTIME) / 86400 ))
-    add_staleness "package.json modified ${PKG_DELTA} day(s) after CLAUDE.md" 1
-  fi
-
-  if command -v jq &>/dev/null; then
-    DEP_COUNT=$(jq '[(.dependencies // {} | length), (.devDependencies // {} | length)] | add' "$PROJECT_DIR/package.json" 2>/dev/null) || DEP_COUNT="0"
-    DOCUMENTED_COUNT=$(grep -oiP '\d+\s*(dependencies|deps)' "$CLAUDE_MD" 2>/dev/null | head -1 | grep -oP '\d+') || true
-    if [[ -n "$DOCUMENTED_COUNT" && -n "$DEP_COUNT" ]]; then
-      DRIFT=$(( DEP_COUNT - DOCUMENTED_COUNT ))
-      DRIFT_ABS=${DRIFT#-}
-      if (( DRIFT_ABS > 5 )); then
-        add_staleness "Dep count drift: CLAUDE.md ~${DOCUMENTED_COUNT}, actual ${DEP_COUNT} (Δ${DRIFT})" 2
-      elif (( DRIFT_ABS > 0 )); then
-        add_staleness "Dep count drift: CLAUDE.md ~${DOCUMENTED_COUNT}, actual ${DEP_COUNT}" 1
-      fi
-    fi
-
-    KEY_DEPS=$(jq -r '(.dependencies // {}) | keys[]' "$PROJECT_DIR/package.json" 2>/dev/null) || true
-    UNDOCUMENTED=()
-    while IFS= read -r dep; do
-      [[ -z "$dep" ]] && continue
-      grep -qi "$dep" "$CLAUDE_MD" 2>/dev/null || UNDOCUMENTED+=("$dep")
-    done <<< "$KEY_DEPS"
-    if (( ${#UNDOCUMENTED[@]} > 5 )); then
-      add_staleness "${#UNDOCUMENTED[@]} production deps not in CLAUDE.md (e.g. ${UNDOCUMENTED[*]:0:5})" 2
-    fi
-  fi
-fi
-
-# --- Python dependency drift ------------------------------------------------
-for PYFILE in "$PROJECT_DIR/pyproject.toml" "$PROJECT_DIR/requirements.txt" "$PROJECT_DIR/setup.py"; do
-  if [[ -f "$PYFILE" ]]; then
-    PY_MTIME=$(file_mtime "$PYFILE")
-    (( PY_MTIME > CLAUDE_MD_MTIME )) && add_staleness "$(basename "$PYFILE") modified after CLAUDE.md" 1
-  fi
-done
-
-# --- Key config files -------------------------------------------------------
-for CFG in "$PROJECT_DIR/tsconfig.json" \
-           "$PROJECT_DIR/.env.example" \
-           "$PROJECT_DIR/docker-compose.yml" \
-           "$PROJECT_DIR/Dockerfile" \
-           "$PROJECT_DIR/Makefile" \
-           "$PROJECT_DIR/Cargo.toml" \
-           "$PROJECT_DIR/go.mod"; do
-  if [[ -f "$CFG" ]]; then
-    CFG_MTIME=$(file_mtime "$CFG")
-    (( CFG_MTIME > CLAUDE_MD_MTIME )) && add_staleness "$(basename "$CFG") modified after CLAUDE.md" 1
-  fi
-done
-
-# --- Git-based checks -------------------------------------------------------
-if command -v git &>/dev/null && [[ -n "$GIT_ROOT" ]]; then
-  CLAUDE_MD_DATE=$(date -d "@$CLAUDE_MD_MTIME" --iso-8601=seconds 2>/dev/null) \
-    || CLAUDE_MD_DATE=$(date -r "$CLAUDE_MD_MTIME" +%Y-%m-%dT%H:%M:%S 2>/dev/null) \
-    || CLAUDE_MD_DATE=""
-
-  if [[ -n "$CLAUDE_MD_DATE" ]]; then
-    COMMITS_SINCE=$(git -C "$PROJECT_DIR" rev-list --count --since="$CLAUDE_MD_DATE" HEAD 2>/dev/null) || COMMITS_SINCE="0"
-    if (( COMMITS_SINCE > 50 )); then
-      add_staleness "${COMMITS_SINCE} commits since CLAUDE.md updated" 2
-    elif (( COMMITS_SINCE > 20 )); then
-      add_staleness "${COMMITS_SINCE} commits since CLAUDE.md updated" 1
-    fi
-
-    CHANGED_FILES=$(git -C "$PROJECT_DIR" diff --name-only --diff-filter=AD HEAD~20..HEAD 2>/dev/null | head -20) || true
-    NEW_TOP_LEVEL=$(echo "$CHANGED_FILES" | { grep -v '/' || true; } | { grep -v '^\.' || true; } | sort -u)
-    if [[ -n "$NEW_TOP_LEVEL" ]]; then
-      NEW_COUNT=$(echo "$NEW_TOP_LEVEL" | wc -l | tr -d ' ')
-      (( NEW_COUNT > 3 )) && add_staleness "${NEW_COUNT} top-level files added/removed recently" 1
-    fi
-  fi
-fi
-
-# --- Lock file drift --------------------------------------------------------
-for LOCK in "$PROJECT_DIR/package-lock.json" \
-            "$PROJECT_DIR/yarn.lock" \
-            "$PROJECT_DIR/pnpm-lock.yaml" \
-            "$PROJECT_DIR/Cargo.lock" \
-            "$PROJECT_DIR/poetry.lock"; do
-  if [[ -f "$LOCK" ]]; then
-    LOCK_MTIME=$(file_mtime "$LOCK")
-    LOCK_DELTA=$(( (LOCK_MTIME - CLAUDE_MD_MTIME) / 86400 ))
-    if (( LOCK_DELTA > 7 )); then
-      add_staleness "$(basename "$LOCK") is ${LOCK_DELTA} days newer than CLAUDE.md" 1
-      break
-    fi
-  fi
-done
-
-# ---------------------------------------------------------------------------
-# 4) Produce output
-# ---------------------------------------------------------------------------
-OUTPUT_PARTS=()
-
-# --- Welcome banner ---------------------------------------------------------
-SKILL_COUNT=$(find "$PROJECT_DIR/skills" -maxdepth 1 -mindepth 1 -type d 2>/dev/null | wc -l | tr -d ' ') || SKILL_COUNT=0
-if (( SKILL_COUNT > 0 )); then
-  OUTPUT_PARTS+=("[MAD SKILLS] Active — ${SKILL_COUNT} skills loaded")
-fi
-
-for part in "${EARLY_CONTEXT_PARTS[@]+"${EARLY_CONTEXT_PARTS[@]}"}"; do
-  OUTPUT_PARTS+=("$part")
-done
-
-OUTPUT_PARTS+=("[SESSION GUARD] ✅ CLAUDE.md found in: $PROJECT_DIR")
-
-if (( STALENESS_SCORE >= STALENESS_THRESHOLD )); then
-  OUTPUT_PARTS+=("")
-  OUTPUT_PARTS+=("[SESSION GUARD] ⚠️  CLAUDE.md appears STALE (score: ${STALENESS_SCORE}/${STALENESS_THRESHOLD})")
-  OUTPUT_PARTS+=("")
-  OUTPUT_PARTS+=("Signals:")
-  for sig in "${STALENESS_SIGNALS[@]}"; do
-    OUTPUT_PARTS+=("  $sig")
-  done
-  OUTPUT_PARTS+=("")
-  OUTPUT_PARTS+=("Use AskUserQuestion to prompt:")
-  OUTPUT_PARTS+=("  Question: \"CLAUDE.md appears out of date (${#STALENESS_SIGNALS[@]} signals detected). What would you like to do?\"")
-  OUTPUT_PARTS+=("  Type: single_select")
-  OUTPUT_PARTS+=("  Options:")
-  OUTPUT_PARTS+=("    1. \"Update it\" — review project structure, deps, recent changes and update CLAUDE.md (preserve user-written notes)")
-  OUTPUT_PARTS+=("    2. \"Show signals\" — list what's drifted before deciding")
-  OUTPUT_PARTS+=("    3. \"Skip\" — continue with current CLAUDE.md")
-  OUTPUT_PARTS+=("")
-elif (( ${#STALENESS_SIGNALS[@]} > 0 )); then
-  OUTPUT_PARTS+=("")
-  OUTPUT_PARTS+=("[SESSION GUARD] ℹ️  Minor drift (score: ${STALENESS_SCORE}/${STALENESS_THRESHOLD}) — not flagging:")
-  for sig in "${STALENESS_SIGNALS[@]}"; do
-    OUTPUT_PARTS+=("  $sig")
-  done
-fi
-
-CONTEXT=$(printf '%s\n' "${OUTPUT_PARTS[@]}")
-
-jq -n --arg ctx "$CONTEXT" '{
-  hookSpecificOutput: {
-    hookEventName: "SessionStart",
-    additionalContext: $ctx
-  }
-}'
-
-# ---------------------------------------------------------------------------
-# 5) Write pending flag for UserPromptSubmit companion hook
-# ---------------------------------------------------------------------------
-PENDING_FILE="$PENDING_DIR/$GUARD_KEY.pending"
-echo "$CONTEXT" > "$PENDING_FILE"
-
-exit 0