@massu/core 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massu/core",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "AI Engineering Governance MCP Server - Session memory, knowledge system, feature registry, code intelligence, rule enforcement, tiered tooling (12 free / 72 total), 55+ workflow commands, 11 agents, 20+ patterns",
   "main": "src/server.ts",

package/src/cli.ts

@@ -52,6 +52,10 @@ async function main(): Promise<void> {
       await runValidateConfig();
       break;
     }
+    case 'config': {
+      await handleConfigSubcommand(args.slice(1));
+      break;
+    }
     case '--help':
     case '-h': {
       printHelp();
@@ -70,6 +74,56 @@ async function main(): Promise<void> {
   }
 }
 
+async function handleConfigSubcommand(configArgs: string[]): Promise<void> {
+  const sub = configArgs[0];
+  const flags = new Set(configArgs.slice(1));
+  switch (sub) {
+    case 'refresh': {
+      const { runConfigRefresh } = await import('./commands/config-refresh.ts');
+      const result = await runConfigRefresh({ dryRun: flags.has('--dry-run') });
+      process.exit(result.exitCode);
+      return;
+    }
+    case 'validate': {
+      const { runValidateConfig } = await import('./commands/doctor.ts');
+      await runValidateConfig();
+      return;
+    }
+    case 'upgrade': {
+      const { runConfigUpgrade } = await import('./commands/config-upgrade.ts');
+      const result = await runConfigUpgrade({
+        rollback: flags.has('--rollback'),
+        ci: flags.has('--ci') || flags.has('--yes'),
+      });
+      process.exit(result.exitCode);
+      return;
+    }
+    case 'doctor': {
+      const { runDoctor } = await import('./commands/doctor.ts');
+      await runDoctor();
+      return;
+    }
+    case 'check-drift': {
+      const { runConfigCheckDrift } = await import('./commands/config-check-drift.ts');
+      const result = await runConfigCheckDrift({ verbose: flags.has('--verbose') });
+      process.exit(result.exitCode);
+      return;
+    }
+    case '--help':
+    case '-h':
+    case undefined: {
+      printConfigHelp();
+      return;
+    }
+    default: {
+      process.stderr.write(`massu: unknown config subcommand: ${sub}\n`);
+      printConfigHelp();
+      process.exit(1);
+      return;
+    }
+  }
+}
+
 function printHelp(): void {
   console.log(`
 Massu AI - Engineering Governance Platform
@@ -82,7 +136,8 @@ Commands:
   doctor            Check installation health
   install-hooks     Install/update Claude Code hooks
   install-commands  Install/update slash commands
-  validate-config   Validate massu.config.yaml
+  validate-config   Validate massu.config.yaml (alias: config validate)
+  config <sub>      Config lifecycle: refresh | validate | upgrade | doctor | check-drift
 
 Options:
   --help, -h        Show this help message
@@ -91,11 +146,34 @@ Options:
 Getting started:
   npx massu init              # Full setup in one command
   npx massu init --help       # Show all init options (--ci, --force, --template)
+  npx massu config --help     # Show config subcommands
 
 Documentation: https://massu.ai/docs
 `);
 }
 
+function printConfigHelp(): void {
+  console.log(`
+massu config <subcommand>
+
+Subcommands:
+  refresh       Re-run detection and apply changes to massu.config.yaml.
+                  --dry-run    Print diff and exit without writing.
+  validate      Validate massu.config.yaml (alias of \`massu validate-config\`).
+  upgrade       Migrate a v1 config to schema_version=2.
+                  --rollback   Restore from .bak file.
+                  --ci, --yes  Non-interactive mode (no prompts).
+  doctor        Run the full health check (alias of \`massu doctor\`).
+  check-drift   CI-safe drift gate; exits 1 on drift.
+                  --verbose    Print detailed changes to stdout.
+
+Examples:
+  npx massu config refresh --dry-run
+  npx massu config upgrade --ci
+  npx massu config check-drift --verbose
+`);
+}
+
 function printVersion(): void {
   try {
     const pkg = JSON.parse(readFileSync(resolve(__dirname, '../package.json'), 'utf-8'));

package/src/commands/config-check-drift.ts

@@ -0,0 +1,132 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * `massu config check-drift` — CI-safe drift gate.
+ *
+ * Reads massu.config.yaml, runs detection, and compares the result with both
+ * the stored fingerprint (if present) and the structural detectDrift() check.
+ *
+ * Flags:
+ *   --verbose   Emit the full changes[] to stdout (field: before -> after).
+ *
+ * Exit codes:
+ *   0  no drift
+ *   1  drift detected
+ *   2  config missing or unparseable
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { resolve } from 'path';
+import { parse as parseYaml } from 'yaml';
+import { runDetection } from '../detect/index.ts';
+import { computeFingerprint, detectDrift, type DriftChange } from '../detect/drift.ts';
+import type { AnyConfig } from '../detect/migrate.ts';
+
+export interface ConfigCheckDriftOptions {
+  verbose?: boolean;
+  cwd?: string;
+  silent?: boolean;
+}
+
+export interface ConfigCheckDriftResult {
+  exitCode: 0 | 1 | 2;
+  drifted: boolean;
+  changes: DriftChange[];
+  storedFingerprint: string | null;
+  currentFingerprint: string | null;
+  message?: string;
+}
+
+function renderChanges(changes: DriftChange[]): string {
+  if (changes.length === 0) return '(none)\n';
+  return changes
+    .map((c) => `  ${c.field}: ${JSON.stringify(c.before)} -> ${JSON.stringify(c.after)}`)
+    .join('\n') + '\n';
+}
+
+export async function runConfigCheckDrift(
+  opts: ConfigCheckDriftOptions = {}
+): Promise<ConfigCheckDriftResult> {
+  const cwd = opts.cwd ?? process.cwd();
+  const configPath = resolve(cwd, 'massu.config.yaml');
+  const log = opts.silent ? () => {} : (s: string) => process.stdout.write(s);
+  const err = opts.silent ? () => {} : (s: string) => process.stderr.write(s);
+
+  if (!existsSync(configPath)) {
+    const message = 'massu.config.yaml not found. Run: npx massu init';
+    err(message + '\n');
+    return {
+      exitCode: 2,
+      drifted: false,
+      changes: [],
+      storedFingerprint: null,
+      currentFingerprint: null,
+      message,
+    };
+  }
+
+  let config: AnyConfig;
+  try {
+    const content = readFileSync(configPath, 'utf-8');
+    const parsed = parseYaml(content);
+    if (!parsed || typeof parsed !== 'object') {
+      throw new Error('config is not a YAML object');
+    }
+    config = parsed as AnyConfig;
+  } catch (e) {
+    const message = `Failed to parse massu.config.yaml: ${e instanceof Error ? e.message : String(e)}`;
+    err(message + '\n');
+    return {
+      exitCode: 2,
+      drifted: false,
+      changes: [],
+      storedFingerprint: null,
+      currentFingerprint: null,
+      message,
+    };
+  }
+
+  const detection = await runDetection(cwd);
+  const currentFp = computeFingerprint(detection);
+  const storedFp =
+    typeof (config.detection as Record<string, unknown> | undefined)?.fingerprint === 'string'
+      ? ((config.detection as Record<string, unknown>).fingerprint as string)
+      : null;
+
+  const report = detectDrift(config, detection);
+  const fingerprintDrift = storedFp !== null && storedFp !== currentFp;
+  const drifted = report.drifted || fingerprintDrift;
+
+  if (!drifted) {
+    log('No drift detected.\n');
+    if (opts.verbose) {
+      log(`Fingerprint: ${currentFp}\n`);
+    }
+    return {
+      exitCode: 0,
+      drifted: false,
+      changes: report.changes,
+      storedFingerprint: storedFp,
+      currentFingerprint: currentFp,
+    };
+  }
+
+  err('Config drift detected; run `npx massu config refresh` to update.\n');
+  if (opts.verbose) {
+    if (storedFp !== null) {
+      log(`Fingerprint: ${storedFp.slice(0, 16)} -> ${currentFp.slice(0, 16)}\n`);
+    } else {
+      log(`Fingerprint (new): ${currentFp.slice(0, 16)}\n`);
+    }
+    log('Changes:\n');
+    log(renderChanges(report.changes));
+  }
+  return {
+    exitCode: 1,
+    drifted: true,
+    changes: report.changes,
+    storedFingerprint: storedFp,
+    currentFingerprint: currentFp,
+  };
+}

package/src/commands/config-refresh.ts

@@ -0,0 +1,224 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * `massu config refresh` — re-run detection, diff against current config, apply
+ * or print-only (--dry-run).
+ *
+ * Merge semantics:
+ *   - Detector-owned keys (framework, paths.source, verification, detection) are REFRESHED.
+ *   - User-authored keys (rules, domains, canonical_paths, accessScopes,
+ *     knownMismatches, dbAccessPattern, analytics, governance, security, team,
+ *     regression, cloud, conventions, autoLearning, verification_types,
+ *     python) are PRESERVED verbatim from the existing config.
+ *
+ * Flags:
+ *   --dry-run    Emit the diff to stdout, exit 0, never write.
+ *   (none)       Interactive: show diff, prompt for confirmation via @clack/prompts.
+ *                When stdin is not a TTY, behaves as --dry-run with a note.
+ *
+ * Exit codes:
+ *   0  success (applied, or dry-run completed)
+ *   1  missing massu.config.yaml (run `massu init`)
+ *   2  unparseable massu.config.yaml
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { resolve } from 'path';
+import { parse as parseYaml } from 'yaml';
+import { runDetection } from '../detect/index.ts';
+import { computeFingerprint } from '../detect/drift.ts';
+import type { AnyConfig } from '../detect/migrate.ts';
+import { buildConfigFromDetection, renderConfigYaml, writeConfigAtomic } from './init.ts';
+
+const PRESERVED_FIELDS = [
+  'rules',
+  'domains',
+  'canonical_paths',
+  'verification_types',
+  'accessScopes',
+  'knownMismatches',
+  'dbAccessPattern',
+  'analytics',
+  'governance',
+  'security',
+  'team',
+  'regression',
+  'cloud',
+  'conventions',
+  'autoLearning',
+  'python',
+] as const;
+
+export interface ConfigRefreshOptions {
+  dryRun?: boolean;
+  cwd?: string;
+  silent?: boolean;
+}
+
+export interface ConfigRefreshResult {
+  exitCode: 0 | 1 | 2;
+  applied: boolean;
+  dryRun: boolean;
+  diff: DiffLine[];
+  message?: string;
+}
+
+export interface DiffLine {
+  kind: 'add' | 'remove' | 'change' | 'same';
+  path: string;
+  before?: unknown;
+  after?: unknown;
+}
+
+function flatten(obj: unknown, prefix = ''): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (obj === null || obj === undefined) {
+    out[prefix || '<root>'] = obj;
+    return out;
+  }
+  if (typeof obj !== 'object' || Array.isArray(obj)) {
+    out[prefix || '<root>'] = obj;
+    return out;
+  }
+  const rec = obj as Record<string, unknown>;
+  for (const [k, v] of Object.entries(rec)) {
+    const p = prefix ? `${prefix}.${k}` : k;
+    if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
+      Object.assign(out, flatten(v, p));
+    } else {
+      out[p] = v;
+    }
+  }
+  return out;
+}
+
+export function computeDiff(before: AnyConfig, after: AnyConfig): DiffLine[] {
+  const b = flatten(before);
+  const a = flatten(after);
+  const keys = new Set<string>([...Object.keys(b), ...Object.keys(a)]);
+  const sorted = [...keys].sort();
+  const lines: DiffLine[] = [];
+  for (const k of sorted) {
+    const bVal = b[k];
+    const aVal = a[k];
+    const bHas = k in b;
+    const aHas = k in a;
+    if (bHas && !aHas) {
+      lines.push({ kind: 'remove', path: k, before: bVal });
+    } else if (!bHas && aHas) {
+      lines.push({ kind: 'add', path: k, after: aVal });
+    } else if (JSON.stringify(bVal) !== JSON.stringify(aVal)) {
+      lines.push({ kind: 'change', path: k, before: bVal, after: aVal });
+    }
+  }
+  return lines;
+}
+
+export function mergeRefresh(existing: AnyConfig, refreshed: AnyConfig): AnyConfig {
+  const out: AnyConfig = { ...refreshed };
+  for (const field of PRESERVED_FIELDS) {
+    if (existing[field] !== undefined) {
+      out[field] = existing[field];
+    }
+  }
+  return out;
+}
+
+function renderDiff(diff: DiffLine[]): string {
+  if (diff.length === 0) return '(no changes)\n';
+  const lines: string[] = [];
+  for (const d of diff) {
+    if (d.kind === 'add') lines.push(`+ ${d.path}: ${JSON.stringify(d.after)}`);
+    else if (d.kind === 'remove') lines.push(`- ${d.path}: ${JSON.stringify(d.before)}`);
+    else if (d.kind === 'change') {
+      lines.push(`~ ${d.path}: ${JSON.stringify(d.before)} -> ${JSON.stringify(d.after)}`);
+    }
+  }
+  return lines.join('\n') + '\n';
+}
+
+export async function runConfigRefresh(opts: ConfigRefreshOptions = {}): Promise<ConfigRefreshResult> {
+  const cwd = opts.cwd ?? process.cwd();
+  const configPath = resolve(cwd, 'massu.config.yaml');
+  const log = opts.silent ? () => {} : (s: string) => process.stdout.write(s);
+
+  if (!existsSync(configPath)) {
+    const message = 'massu.config.yaml not found. Run: npx massu init';
+    if (!opts.silent) process.stderr.write(message + '\n');
+    return { exitCode: 1, applied: false, dryRun: !!opts.dryRun, diff: [], message };
+  }
+
+  let existing: AnyConfig;
+  try {
+    const content = readFileSync(configPath, 'utf-8');
+    const parsed = parseYaml(content);
+    if (!parsed || typeof parsed !== 'object') {
+      throw new Error('config is not a YAML object');
+    }
+    existing = parsed as AnyConfig;
+  } catch (err) {
+    const message = `Failed to parse massu.config.yaml: ${err instanceof Error ? err.message : String(err)}`;
+    if (!opts.silent) process.stderr.write(message + '\n');
+    return { exitCode: 2, applied: false, dryRun: !!opts.dryRun, diff: [], message };
+  }
+
+  const detection = await runDetection(cwd);
+  const refreshed = buildConfigFromDetection({
+    projectRoot: cwd,
+    detection,
+    projectName: typeof (existing.project as Record<string, unknown> | undefined)?.name === 'string'
+      ? (existing.project as Record<string, unknown>).name as string
+      : undefined,
+  });
+  // buildConfigFromDetection already stamps detection.fingerprint. Double-check.
+  if (!(refreshed.detection as Record<string, unknown> | undefined)?.fingerprint) {
+    refreshed.detection = { fingerprint: computeFingerprint(detection) };
+  }
+
+  const merged = mergeRefresh(existing, refreshed);
+  const diff = computeDiff(existing, merged);
+
+  if (opts.dryRun) {
+    log('Config diff (dry-run; no changes written):\n');
+    log(renderDiff(diff));
+    return { exitCode: 0, applied: false, dryRun: true, diff };
+  }
+
+  if (diff.length === 0) {
+    log('No changes needed — config is already up to date.\n');
+    return { exitCode: 0, applied: false, dryRun: false, diff };
+  }
+
+  // Interactive prompt; fall back to dry-run semantics when not a TTY.
+  if (!process.stdin.isTTY) {
+    log('Config diff (non-interactive; pass --dry-run to suppress this note or run interactively to apply):\n');
+    log(renderDiff(diff));
+    return {
+      exitCode: 0,
+      applied: false,
+      dryRun: false,
+      diff,
+      message: 'non-interactive shell; no changes written',
+    };
+  }
+
+  log('Config diff:\n');
+  log(renderDiff(diff));
+  const { confirm } = await import('@clack/prompts');
+  const apply = await confirm({ message: 'Apply these changes to massu.config.yaml?' });
+  if (apply !== true) {
+    log('Aborted; no changes written.\n');
+    return { exitCode: 0, applied: false, dryRun: false, diff, message: 'aborted by user' };
+  }
+
+  const yamlContent = renderConfigYaml(merged);
+  const writeRes = writeConfigAtomic(configPath, yamlContent);
+  if (!writeRes.validated) {
+    const message = `Failed to write config: ${writeRes.error}`;
+    if (!opts.silent) process.stderr.write(message + '\n');
+    return { exitCode: 2, applied: false, dryRun: false, diff, message };
+  }
+  log('Config refreshed.\n');
+  return { exitCode: 0, applied: true, dryRun: false, diff };
+}

package/src/commands/config-upgrade.ts

@@ -0,0 +1,126 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * `massu config upgrade` — migrate a v1 `massu.config.yaml` to schema_version=2.
+ *
+ * Flags:
+ *   --rollback    Restore massu.config.yaml from massu.config.yaml.bak.
+ *   --ci / --yes  Non-interactive; no prompts; detector wins on conflicts.
+ *
+ * Safety:
+ *   - Writes .bak of the original before overwriting.
+ *   - Atomic write via writeConfigAtomic (tmp + rename).
+ *   - Idempotent: running on a schema_version=2 config is a no-op.
+ *
+ * Exit codes:
+ *   0  success (migrated, rolled back, or already current)
+ *   1  config missing / rollback source missing
+ *   2  parse or write failure
+ */
+
+import { existsSync, readFileSync, writeFileSync, copyFileSync, unlinkSync } from 'fs';
+import { resolve } from 'path';
+import { parse as parseYaml } from 'yaml';
+import { runDetection } from '../detect/index.ts';
+import { computeFingerprint } from '../detect/drift.ts';
+import { migrateV1ToV2, type AnyConfig } from '../detect/migrate.ts';
+import { renderConfigYaml, writeConfigAtomic } from './init.ts';
+
+export interface ConfigUpgradeOptions {
+  rollback?: boolean;
+  ci?: boolean;
+  cwd?: string;
+  silent?: boolean;
+}
+
+export interface ConfigUpgradeResult {
+  exitCode: 0 | 1 | 2;
+  action: 'migrated' | 'already-current' | 'rolled-back' | 'none';
+  message?: string;
+}
+
+export async function runConfigUpgrade(opts: ConfigUpgradeOptions = {}): Promise<ConfigUpgradeResult> {
+  const cwd = opts.cwd ?? process.cwd();
+  const configPath = resolve(cwd, 'massu.config.yaml');
+  const bakPath = `${configPath}.bak`;
+  const log = opts.silent ? () => {} : (s: string) => process.stdout.write(s);
+  const err = opts.silent ? () => {} : (s: string) => process.stderr.write(s);
+
+  if (opts.rollback) {
+    if (!existsSync(bakPath)) {
+      const message = `No backup found at ${bakPath}`;
+      err(message + '\n');
+      return { exitCode: 1, action: 'none', message };
+    }
+    try {
+      copyFileSync(bakPath, configPath);
+      unlinkSync(bakPath);
+      log('Config restored from backup.\n');
+      return { exitCode: 0, action: 'rolled-back' };
+    } catch (e) {
+      const message = `Rollback failed: ${e instanceof Error ? e.message : String(e)}`;
+      err(message + '\n');
+      return { exitCode: 2, action: 'none', message };
+    }
+  }
+
+  if (!existsSync(configPath)) {
+    const message = 'massu.config.yaml not found. Run: npx massu init';
+    err(message + '\n');
+    return { exitCode: 1, action: 'none', message };
+  }
+
+  let existing: AnyConfig;
+  try {
+    const content = readFileSync(configPath, 'utf-8');
+    const parsed = parseYaml(content);
+    if (!parsed || typeof parsed !== 'object') {
+      throw new Error('config is not a YAML object');
+    }
+    existing = parsed as AnyConfig;
+  } catch (e) {
+    const message = `Failed to parse massu.config.yaml: ${e instanceof Error ? e.message : String(e)}`;
+    err(message + '\n');
+    return { exitCode: 2, action: 'none', message };
+  }
+
+  const schemaVersion = existing.schema_version;
+  if (schemaVersion === 2) {
+    log('Config is already at schema_version=2; nothing to do.\n');
+    return { exitCode: 0, action: 'already-current' };
+  }
+
+  const detection = await runDetection(cwd);
+  const v2 = migrateV1ToV2(existing, detection);
+  v2.detection = {
+    ...(v2.detection as Record<string, unknown> | undefined ?? {}),
+    fingerprint: computeFingerprint(detection),
+  };
+
+  // Back up original before any write.
+  try {
+    const original = readFileSync(configPath, 'utf-8');
+    writeFileSync(bakPath, original, 'utf-8');
+  } catch (e) {
+    const message = `Failed to write backup: ${e instanceof Error ? e.message : String(e)}`;
+    err(message + '\n');
+    return { exitCode: 2, action: 'none', message };
+  }
+
+  const yamlContent = renderConfigYaml(v2);
+  const writeRes = writeConfigAtomic(configPath, yamlContent);
+  if (!writeRes.validated) {
+    const message = `Failed to write upgraded config: ${writeRes.error}`;
+    err(message + '\n');
+    return { exitCode: 2, action: 'none', message };
+  }
+
+  // Non-interactive mode just proceeds; interactive mode currently has no
+  // prompt on migrate (the migrator is deterministic and always user-preserving).
+  // --ci / --yes remain accepted for script-pipeline safety.
+  void opts.ci;
+
+  log(`Config upgraded to schema_version=2. Backup saved at ${bakPath}\n`);
+  return { exitCode: 0, action: 'migrated' };
+}

package/src/commands/init.ts

@@ -40,6 +40,7 @@ import {
   type SupportedLanguage,
   type VRCommandSet,
 } from '../detect/index.ts';
+import { computeFingerprint } from '../detect/drift.ts';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -430,6 +431,9 @@ export function buildConfigFromDetection(
     config.verification = verification;
   }
 
+  // P5-002: stamp a stack fingerprint so session-start can detect drift later.
+  config.detection = { fingerprint: computeFingerprint(detection) };
+
   // Preserve legacy `python` block for v1 consumers (domain-enforcer, etc.).
   // Per Phase 0 P1-009 (b): python legacy config coexists with languages.python.
   if (languages.includes('python')) {

package/src/hooks/session-start.ts

@@ -11,8 +11,11 @@
 import { getMemoryDb, getSessionSummaries, getRecentObservations, getFailedAttempts, getCrossTaskProgress, autoDetectTaskId, linkSessionToTask, createSession } from '../memory-db.ts';
 import { getConfig, getResolvedPaths } from '../config.ts';
 import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
+import { join, resolve } from 'path';
+import { parse as parseYaml } from 'yaml';
 import type Database from 'better-sqlite3';
+import { runDetection } from '../detect/index.ts';
+import { computeFingerprint } from '../detect/drift.ts';
 
 interface HookInput {
   session_id: string;
@@ -63,6 +66,12 @@ async function main(): Promise<void> {
       if (context.trim()) {
         process.stdout.write(context);
       }
+
+      // P5-001: drift banner (runs after memory context, independent of it).
+      const driftBanner = await buildDriftBanner();
+      if (driftBanner) {
+        process.stdout.write(driftBanner);
+      }
     } finally {
       db.close();
     }
@@ -244,6 +253,38 @@ function readStdin(): Promise<string> {
   });
 }
 
+/**
+ * P5-001: compare the fingerprint stored in massu.config.yaml (detection.fingerprint,
+ * stamped by init/refresh/upgrade) against a freshly-computed fingerprint. If they
+ * disagree, return a plain-text banner. Returns '' on any error or when the
+ * config has no fingerprint (back-compat with v1 configs).
+ */
+async function buildDriftBanner(): Promise<string> {
+  try {
+    const configPath = resolve(process.cwd(), 'massu.config.yaml');
+    if (!existsSync(configPath)) return '';
+    const content = readFileSync(configPath, 'utf-8');
+    const parsed = parseYaml(content) as Record<string, unknown> | null;
+    if (!parsed || typeof parsed !== 'object') return '';
+    const det = parsed.detection as Record<string, unknown> | undefined;
+    const storedFp = typeof det?.fingerprint === 'string' ? (det.fingerprint as string) : null;
+    if (!storedFp) return '';
+    const detection = await runDetection(process.cwd());
+    const currentFp = computeFingerprint(detection);
+    if (currentFp === storedFp) return '';
+    return (
+      '=== Massu Config Drift ===\n' +
+      'Detected stack has changed since last config refresh.\n' +
+      `Fingerprint:  ${storedFp.slice(0, 16)}  ->  ${currentFp.slice(0, 16)}\n` +
+      'Run: npx massu config refresh\n' +
+      '=== END ===\n'
+    );
+  } catch (_e) {
+    // Never block session start on drift-check failure.
+    return '';
+  }
+}
+
 function safeParseJson(json: string): Record<string, string> | null {
   try {
     return JSON.parse(json);