@slamb2k/mad-skills 2.0.10 → 2.0.12

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mad-skills",
   "description": "AI-assisted planning, development and governance tools",
-  "version": "2.0.10",
+  "version": "2.0.12",
   "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 \"$HOME/.claude/hooks/session-guard.js\" check", "timeout": 30 }]
+    }],
+    "UserPromptSubmit": [{
+      "hooks": [{ "type": "command", "command": "node \"$HOME/.claude/hooks/session-guard.js\" remind", "timeout": 10 }]
+    }]
   }
 }

package/hooks/lib/banner.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const config = require('./config');
+
+// 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.js

@@ -0,0 +1,39 @@
+'use strict';
+
+module.exports = {
+  version: '1.0.0',
+
+  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.js

@@ -0,0 +1,118 @@
+'use strict';
+
+const { existsSync } = require('fs');
+const { join, dirname, basename } = require('path');
+const config = require('./config');
+const { git, readJson, countFiles } = require('./utils');
+
+/**
+ * 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.js

@@ -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.js

@@ -0,0 +1,154 @@
+'use strict';
+
+const { existsSync } = require('fs');
+const { join } = require('path');
+const config = require('./config');
+const { fileMtime, git, readJson, readText, getDirectories } = require('./utils');
+
+/**
+ * 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.js

@@ -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.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const { existsSync } = require('fs');
+const { join, basename } = require('path');
+const { homedir } = require('os');
+const config = require('./config');
+const { readJson, git } = require('./utils');
+
+/**
+ * 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.js

@@ -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.js

@@ -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');
+const state = require('./lib/state');
+const { OutputBuilder } = require('./lib/output');
+const { getBanner, BANNER_MARKER } = require('./lib/banner');
+const { checkGit } = require('./lib/git-checks');
+const { checkTaskList } = require('./lib/task-checks');
+const { checkStaleness } = require('./lib/staleness');
+
+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/hooks/session-guard.sh

@@ -188,10 +188,15 @@ 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
+  for CFG_FILE in "$SETTINGS_FILE" "$HOME/.claude/settings.json"; do
+    if [[ -f "$CFG_FILE" ]]; then
+      TASK_ID=$(jq -r '.env.CLAUDE_CODE_TASK_LIST_ID // empty' "$CFG_FILE" 2>/dev/null) || true
+      if [[ -n "$TASK_ID" ]]; then
+        TASK_LIST_CONFIGURED=true
+        break
+      fi
+    fi
+  done
 fi
 
 if [[ "$TASK_LIST_CONFIGURED" == false && -n "$GIT_ROOT" ]]; then
@@ -346,12 +351,6 @@ done
 # ---------------------------------------------------------------------------
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slamb2k/mad-skills",
-  "version": "2.0.10",
+  "version": "2.0.12",
   "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:36:03.798Z",
+  "generated": "2026-03-09T13:01:19.482Z",
   "count": 8,
   "skills": [
     {