sigmap 7.10.0 → 7.12.0

package/gen-context.js

@@ -25,222 +25,245 @@ function __require(key) {
 // ── ./src/conventions/conflicts ──
 // ── ./src/conventions/inject ──
 // ── ./src/scaffold/propose ──
-__factories["./src/scaffold/propose"] = function(module, exports) {
+// ── ./src/plan/verify-plan ──
+// ── ./src/cache/freshen ──
+// ── ./src/review/review-pr ──
+__factories["./src/review/review-pr"] = function(module, exports) {
   
   /**
-   * Scaffold proposal with a confidence floor (IMPL.md §5 — Cause 3).
+   * review-pr (IMPL.md §6 step 4 — last guard stage of the `create` pipeline).
    *
-   * Proposes a convention-matched structure for a new module — filename in the
-   * repo's dominant naming style, the export style to use, and a matching test
-   * file — but only when the conventions are consistent enough. Below a hard
-   * floor it refuses and surfaces the conflict, because a wrong proposal
-   * systematizes bad code. Pure, zero-dependency, bundle-safe; reuses the
-   * conventions primitives.
+   * Audits a diff for drift and side effects after a PR is opened: scope drift,
+   * edits to high-fan-in "god-node" files, source changes without matching tests,
+   * and changes to security-sensitive files. Pure (takes a changed-file list),
+   * zero-dependency, bundle-safe; reuses the impact graph for blast radius.
    */
 
-  const { toNamingStyle, analyzeConflicts } = __require('./src/conventions/conflicts');
-
-  // Soft threshold is configurable; the hard floor is not (IMPL.md §5.1).
-  const DEFAULT_THRESHOLD = 0.7;
-  const HARD_FLOOR = 0.5;
+  const path = require('path');
+  const { analyzeImpact } = __require('./src/graph/impact');
+
+  const SECURITY_PATTERNS = [
+    /(^|\/)\.env(\.|$)/i,
+    /(^|\/)(secrets?|credentials?)(\/|\.|$)/i,
+    /(^|\/)auth(\/|\.|-)/i,
+    /(^|\/)package(-lock)?\.json$/,
+    /(^|\/)(yarn\.lock|pnpm-lock\.yaml)$/,
+    /(^|\/)\.github\/workflows\//,
+    /(^|\/)Dockerfile/i,
+    /\.(pem|key|crt|p12)$/i,
+  ];
 
-  /** Tier for a consistency score (matches the conventions tiers). */
-  function _tier(pct) {
-    if (pct >= 0.9) return 'consistent';
-    if (pct >= 0.7) return 'mostly';
-    return 'inconsistent';
-  }
+  const SRC_EXTS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.py', '.go', '.rs', '.java', '.rb', '.php']);
+  const GOD_NODE_THRESHOLD = 15; // transitive dependents → high-fan-in "god node"
+  const SCOPE_DIR_THRESHOLD = 5; // distinct top-level dirs → scope drift
 
-  /** Strip any extension/compound suffix from a requested name → bare stem. */
-  function _stem(name) {
-    const s = String(name || '').trim();
-    const slash = s.lastIndexOf('/');
-    const base = slash >= 0 ? s.slice(slash + 1) : s;
-    const dot = base.indexOf('.');
-    return dot > 0 ? base.slice(0, dot) : base;
+  function isTestFile(p) {
+    return /\.(test|spec)\.[jt]sx?$|(^|\/)test_|_test\.(py|go)$|(^|\/)(tests?|__tests__|spec)\//.test(p);
   }
-
-  /** Test file path for a styled stem given the detected framework + ext. */
-  function _testFile(styledStem, framework, ext) {
-    if (framework === 'pytest' || framework === 'unittest') {
-      return `test_${toNamingStyle(styledStem, 'snake_case')}.py`;
-    }
-    return `${styledStem}.test.${ext}`;
+  function isSource(p) {
+    return SRC_EXTS.has(path.extname(p).toLowerCase()) && !isTestFile(p);
   }
 
   /**
-   * Propose a convention-matched scaffold, gated by a confidence floor.
-   * @param {string} name desired module name (any casing; extension ignored)
-   * @param {object} conventions an `extractConventions` result
+   * Audit a changed-file list.
+   * @param {Array<{path:string,status:string}>|string[]} changedFiles
+   * @param {string} cwd
    * @param {object} [opts]
-   * @param {number} [opts.threshold=0.7] soft threshold (clamped to ≥ hard floor)
-   * @param {boolean} [opts.force=false] allow proposing below the soft threshold
-   *   (never below the hard floor)
-   * @param {string} [opts.ext='js'] file extension for the proposed files
-   * @returns {{ ok:boolean, refused:boolean, name:string, tier:string,
-   *   confidence:number, threshold:number, hardFloor:number, forced:boolean,
-   *   warning:string|null, reason:string, proposal:object|null, conflicts:object }}
+   * @param {number} [opts.godNodeThreshold=15]
+   * @param {number} [opts.scopeThreshold=5]
+   * @returns {{ findings: object[], blast: object[], summary: object }}
    */
-  function proposeScaffold(name, conventions, opts = {}) {
-    const threshold = Math.max(HARD_FLOOR, opts.threshold != null ? opts.threshold : DEFAULT_THRESHOLD);
-    const force = !!opts.force;
-    const ext = opts.ext || 'js';
-    const fileNaming = (conventions && conventions.fileNaming) || { dominant: null, dominantPct: 0, total: 0 };
-    const exportStyle = (conventions && conventions.exportStyle) || { dominant: null };
-    const confidence = fileNaming.dominantPct || 0;
-    const tier = fileNaming.total > 0 ? _tier(confidence) : 'unknown';
-    const conflicts = analyzeConflicts(conventions || {});
-
-    const base = {
-      ok: false, refused: true, name: String(name || ''), tier, confidence,
-      threshold, hardFloor: HARD_FLOOR, forced: false, warning: null,
-      reason: '', proposal: null, conflicts,
-    };
-
-    if (!fileNaming.dominant || fileNaming.total === 0) {
-      return { ...base, reason: 'no file-naming convention detected — cannot propose a name' };
-    }
-    if (confidence < HARD_FLOOR) {
-      return {
-        ...base,
-        reason: `file-naming consistency ${(confidence * 100).toFixed(0)}% is below the hard floor ${(HARD_FLOOR * 100).toFixed(0)}% — refusing (not overridable)`,
-      };
-    }
-    if (confidence < threshold && !force) {
-      return {
-        ...base,
-        reason: `file-naming consistency ${(confidence * 100).toFixed(0)}% is below the threshold ${(threshold * 100).toFixed(0)}% — refusing (use --force to override above the ${(HARD_FLOOR * 100).toFixed(0)}% floor)`,
-      };
+  function reviewPr(changedFiles, cwd, opts = {}) {
+    const godThreshold = opts.godNodeThreshold != null ? opts.godNodeThreshold : GOD_NODE_THRESHOLD;
+    const scopeThreshold = opts.scopeThreshold != null ? opts.scopeThreshold : SCOPE_DIR_THRESHOLD;
+    const files = (changedFiles || []).map((f) => (typeof f === 'string' ? { path: f, status: 'M' } : f));
+
+    const findings = [];
+    const paths = files.map((f) => f.path);
+    const live = files.filter((f) => f.status !== 'D');
+    const srcChanged = live.filter((f) => isSource(f.path)).map((f) => f.path);
+    const testChanged = paths.filter(isTestFile);
+
+    // 1. Missing tests: a changed source file with no matching changed test file.
+    for (const s of srcChanged) {
+      const stem = path.basename(s).replace(/\.[^.]+$/, '');
+      const covered = testChanged.some((t) => path.basename(t).includes(stem));
+      if (!covered) findings.push({ type: 'missing-tests', file: s, severity: 'warn' });
+    }
+
+    // 2. Security-sensitive files.
+    for (const f of live) {
+      if (SECURITY_PATTERNS.some((re) => re.test(f.path))) {
+        findings.push({ type: 'security-file', file: f.path, severity: 'warn' });
+      }
+    }
+
+    // 3. God-node edits (high blast radius).
+    const blast = [];
+    if (srcChanged.length) {
+      let impacts = [];
+      try { impacts = analyzeImpact(srcChanged, cwd, {}); } catch (_) { impacts = []; }
+      for (const { file, impact } of impacts) {
+        blast.push({ file, totalImpact: impact.totalImpact });
+        if (impact.totalImpact > godThreshold) {
+          findings.push({ type: 'god-node', file, count: impact.totalImpact, severity: 'warn' });
+        }
+      }
+      blast.sort((a, b) => b.totalImpact - a.totalImpact);
     }
 
-    const styledStem = toNamingStyle(_stem(name), fileNaming.dominant);
-    const forced = confidence < threshold && force;
-    const proposal = {
-      filename: `${styledStem}.${ext}`,
-      namingStyle: fileNaming.dominant,
-      exportStyle: exportStyle.dominant || 'named',
-      testFile: _testFile(styledStem, conventions.testFramework, ext),
-      testFramework: conventions.testFramework || null,
-    };
+    // 4. Scope drift: distinct top-level directories touched.
+    const dirs = [...new Set(paths.map((p) => (p.includes('/') ? p.split('/')[0] : '.')))];
+    if (dirs.length > scopeThreshold) {
+      findings.push({ type: 'scope-drift', dirs, count: dirs.length, threshold: scopeThreshold, severity: 'warn' });
+    }
 
+    const byType = findings.reduce((a, f) => { a[f.type] = (a[f.type] || 0) + 1; return a; }, {});
     return {
-      ...base,
-      ok: true,
-      refused: false,
-      forced,
-      warning: forced
-        ? `proposed below the ${(threshold * 100).toFixed(0)}% threshold (--force); conventions are only ${tier}`
-        : null,
-      reason: forced ? 'forced proposal above the hard floor' : `conventions are ${tier} — proposing`,
-      proposal,
+      findings,
+      blast,
+      summary: {
+        filesChanged: files.length,
+        sourceChanged: srcChanged.length,
+        testsChanged: testChanged.length,
+        findings: findings.length,
+        byType,
+        ok: findings.length === 0,
+      },
     };
   }
 
-  module.exports = { proposeScaffold, DEFAULT_THRESHOLD, HARD_FLOOR };
+  module.exports = { reviewPr, SECURITY_PATTERNS, GOD_NODE_THRESHOLD, SCOPE_DIR_THRESHOLD };
   
 };
 
-__factories["./src/conventions/inject"] = function(module, exports) {
+__factories["./src/cache/freshen"] = function(module, exports) {
   
   /**
-   * CLAUDE.md convention injection (IMPL.md §7 Phase 2 / §8 step 5).
+   * Read-time self-heal (IMPL.md Layer 1, "safety net" tier).
    *
-   * Renders the conventions detected by `extractConventions` into a
-   * marker-delimited markdown block and injects it into CLAUDE.md so an agent
-   * reading the file plans grounded in the repo's house style. Idempotent and
-   * marker-scoped — it never touches human content or the `## Auto-generated
-   * signatures` block. Pure string transforms; zero-dependency, bundle-safe.
+   * Keeps the sig-cache in line with the current source tree so the index reflects
+   * on-disk reality even when no write hook was called. Re-extracts files modified
+   * since the context file was generated (bounded to actual session edits, not the
+   * whole tree), drops cache entries for deleted files, and persists. buildSigIndex
+   * already merges the cache, so the next read is fresh.
+   *
+   * Throttled per cwd. Skips entirely when there is no generated index to heal
+   * (a cold repo should run `generate` or use the notify hooks).
+   *
+   * Zero-dependency, bundle-safe (fs + dispatch + sig-cache).
    */
 
-  const START = '<!-- sigmap-conventions:start -->';
-  const END = '<!-- sigmap-conventions:end -->';
+  const fs = require('fs');
+  const path = require('path');
+  const { loadCache, saveCache, getChangedFiles } = __require('./src/cache/sig-cache');
+  const { extractFile, langFor } = __require('./src/extractors/dispatch');
 
-  const TIER_NOTE = {
-    consistent: 'consistent — match it',
-    mostly: 'dominant, with some drift',
-    inconsistent: 'no clear convention — check neighboring files',
-  };
+  const DEFAULT_SRC_DIRS = ['src', 'app', 'lib', 'packages', 'services', 'api'];
+  const DEFAULT_EXCLUDE = [
+    'node_modules', '.git', 'dist', 'build', 'out', '__pycache__',
+    '.next', 'coverage', 'target', 'vendor', '.context',
+  ];
+  const CONTEXT_PATHS = [
+    ['.github', 'copilot-instructions.md'],
+    ['CLAUDE.md'], ['AGENTS.md'], ['.github', 'context-cold.md'],
+  ];
+  const THROTTLE_MS = 1500;
+  const _lastRun = new Map();
 
-  const NAMES = {
-    fileNaming: 'File naming',
-    exportStyle: 'Export style',
-  };
+  function _readConfig(cwd) {
+    try {
+      const cfg = JSON.parse(fs.readFileSync(path.join(cwd, 'gen-context.config.json'), 'utf8'));
+      return cfg && typeof cfg === 'object' ? cfg : {};
+    } catch (_) { return {}; }
+  }
 
-  const _pct = (n) => `${Math.round(n * 100)}%`;
+  function _pkgVersion(cwd) {
+    try { return JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8')).version || '0.0.0'; }
+    catch (_) { return '0.0.0'; }
+  }
 
-  function _conventionLine(label, conv) {
-    if (!conv || conv.total === 0 || !conv.dominant) return null;
-    const note = TIER_NOTE[conv.tier] || conv.tier;
-    let line = `- **${label}:** ${conv.dominant} (${_pct(conv.dominantPct)} — ${note}).`;
-    const others = conv.variants.slice(1).filter((v) => v.pct > 0);
-    if (others.length) {
-      line += ` Variants: ${others.map((v) => `${v.label} ${_pct(v.pct)}`).join(', ')}.`;
+  /** Newest mtime among existing generated context files, or 0 if none. */
+  function _contextMtime(cwd) {
+    let newest = 0;
+    for (const parts of CONTEXT_PATHS) {
+      try { newest = Math.max(newest, fs.statSync(path.join(cwd, ...parts)).mtimeMs); } catch (_) {}
+    }
+    return newest;
+  }
+
+  function _walk(dir, exclude, out, depth, maxDepth) {
+    if (depth > maxDepth) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; }
+    for (const e of entries) {
+      if (exclude.has(e.name)) continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) _walk(full, exclude, out, depth + 1, maxDepth);
+      else if (e.isFile() && langFor(e.name)) out.push(full);
     }
-    return line;
   }
 
   /**
-   * Render the conventions block (including its start/end markers).
-   * @param {object} result an `extractConventions` result
-   * @param {string} [version] SigMap version for the footer
-   * @returns {string}
+   * Re-extract source files changed since the last generate; drop deleted files.
+   * @param {string} cwd
+   * @param {{force?:boolean, now?:number}} [opts]
+   * @returns {number} cache entries touched
    */
-  function renderConventionsBlock(result, version) {
-    const lines = [];
-    for (const key of ['fileNaming', 'exportStyle']) {
-      const l = _conventionLine(NAMES[key], result && result[key]);
-      if (l) lines.push(l);
-    }
-    if (result && result.testFramework) {
-      lines.push(`- **Test framework:** ${result.testFramework}.`);
+  function freshen(cwd, opts = {}) {
+    const now = opts.now != null ? opts.now : Date.now();
+    if (!opts.force) {
+      if (now - (_lastRun.get(cwd) || 0) < THROTTLE_MS) return 0;
     }
+    _lastRun.set(cwd, now);
 
-    const body = lines.length
-      ? lines
-      : ['- No conventions detected yet (run `sigmap conventions` on a TS/JS/Python repo).'];
+    try {
+      const version = _pkgVersion(cwd);
+      const cache = loadCache(cwd, version);
+      const ctxMtime = _contextMtime(cwd);
+      // Nothing to heal: no generated context AND no live cache overlay.
+      if (ctxMtime === 0 && cache.size === 0) return 0;
 
-    const ver = version ? ` v${version}` : '';
-    return [
-      START,
-      '## Conventions (auto-detected by SigMap)',
-      '',
-      'Match these when writing or editing code (TS/JS/Python):',
-      '',
-      ...body,
-      '',
-      `<sub>Generated by SigMap${ver} · run \`sigmap conventions --inject\` to refresh.</sub>`,
-      END,
-    ].join('\n');
-  }
+      const cfg = _readConfig(cwd);
+      const srcDirs = Array.isArray(cfg.srcDirs) && cfg.srcDirs.length ? cfg.srcDirs : DEFAULT_SRC_DIRS;
+      const exclude = new Set([...DEFAULT_EXCLUDE, ...(Array.isArray(cfg.exclude) ? cfg.exclude : [])]);
+      const maxDepth = Number.isFinite(cfg.maxDepth) ? cfg.maxDepth : 8;
 
-  /**
-   * Inject (or replace) the conventions block in existing CLAUDE.md content.
-   * Replaces an existing marked block in place; appends one when absent.
-   * Idempotent — never touches content outside the markers.
-   * @param {string} existing current file content ('' if the file is new)
-   * @param {string} block the block returned by `renderConventionsBlock`
-   * @returns {string}
-   */
-  function injectConventions(existing, block) {
-    const src = String(existing || '');
-    const startIdx = src.indexOf(START);
-    if (startIdx !== -1) {
-      const endIdx = src.indexOf(END, startIdx);
-      if (endIdx !== -1) {
-        const before = src.slice(0, startIdx);
-        const after = src.slice(endIdx + END.length);
-        return before + block + after;
+      const files = [];
+      for (const d of srcDirs) {
+        const abs = path.isAbsolute(d) ? d : path.join(cwd, d);
+        if (fs.existsSync(abs)) _walk(abs, exclude, files, 0, maxDepth);
       }
+
+      // Candidates = files modified since the context was generated, or not yet cached.
+      const candidates = files.filter((f) => {
+        try { return fs.statSync(f).mtimeMs > ctxMtime || !cache.has(f); } catch (_) { return false; }
+      });
+      const { changed } = getChangedFiles(candidates, cache);
+
+      let touched = 0;
+      for (const f of changed) {
+        try {
+          const sigs = extractFile(f, fs.readFileSync(f, 'utf8'));
+          cache.set(f, { mtime: fs.statSync(f).mtimeMs, sigs });
+          touched++;
+        } catch (_) {}
+      }
+      // Note: deletions are NOT swept here — a cache entry may be a `notify`
+      // overlay for a file not yet on disk. Explicit removal is `notify_file_deleted`.
+
+      if (touched > 0) saveCache(cwd, version, cache);
+      return touched;
+    } catch (_) {
+      return 0;
     }
-    if (src.trim() === '') return block + '\n';
-    const sep = src.endsWith('\n') ? '\n' : '\n\n';
-    return src + sep + block + '\n';
   }
 
-  module.exports = { renderConventionsBlock, injectConventions, START, END };
+  module.exports = { freshen };
   
 };
 
+// ── ./src/conventions/conflicts ──
 __factories["./src/conventions/conflicts"] = function(module, exports) {
   
   /**
@@ -355,6 +378,7 @@ __factories["./src/conventions/conflicts"] = function(module, exports) {
   
 };
 
+// ── ./src/conventions/extract ──
 __factories["./src/conventions/extract"] = function(module, exports) {
   
   /**
@@ -399,24 +423,42 @@ __factories["./src/conventions/extract"] = function(module, exports) {
     return 'other';
   }
 
+  const MAX_EXAMPLES = 3;
+
   /**
    * Score a set of categorical observations into a dominant convention plus its
    * consistency tier. The reusable primitive (IMPL.md §5.2).
    * @param {string[]} labels observed category for each sample (e.g. naming styles)
+   * @param {string[]} [refs] optional identifier (e.g. file name) parallel to
+   *   `labels`; when given, each variant carries up to 3 `examples`.
    * @returns {{ dominant: string|null, dominantPct: number, total: number,
-   *             variants: Array<{label:string, count:number, pct:number}>,
+   *             variants: Array<{label:string, count:number, pct:number, examples?:string[]}>,
    *             tier: 'consistent'|'mostly'|'inconsistent'|'unknown' }}
    */
-  function scoreConvention(labels) {
-    const list = (labels || []).filter((l) => l != null && l !== 'other');
-    const total = list.length;
+  function scoreConvention(labels, refs) {
+    const all = labels || [];
+    const counts = new Map();
+    const examples = new Map();
+    let total = 0;
+    for (let i = 0; i < all.length; i++) {
+      const l = all[i];
+      if (l == null || l === 'other') continue;
+      total++;
+      counts.set(l, (counts.get(l) || 0) + 1);
+      if (refs && refs[i] != null) {
+        const ex = examples.get(l) || [];
+        if (ex.length < MAX_EXAMPLES) { ex.push(refs[i]); examples.set(l, ex); }
+      }
+    }
     if (total === 0) {
       return { dominant: null, dominantPct: 0, total: 0, variants: [], tier: 'unknown' };
     }
-    const counts = new Map();
-    for (const l of list) counts.set(l, (counts.get(l) || 0) + 1);
     const variants = [...counts.entries()]
-      .map(([label, count]) => ({ label, count, pct: count / total }))
+      .map(([label, count]) => {
+        const v = { label, count, pct: count / total };
+        if (refs) v.examples = examples.get(label) || [];
+        return v;
+      })
       .sort((a, b) => b.count - a.count || a.label.localeCompare(b.label));
     const top = variants[0];
     let tier = 'inconsistent';
@@ -488,157 +530,365 @@ __factories["./src/conventions/extract"] = function(module, exports) {
   function extractConventions(cwd, files) {
     const scoped = (files || []).filter((f) => SCOPED_EXTS.has(path.extname(f).toLowerCase()));
     const namingLabels = [];
+    const namingRefs = [];
     const exportLabels = [];
+    const exportRefs = [];
     for (const f of scoped) {
       const base = path.basename(f);
       // Skip test files for the naming convention (they have their own naming).
       if (!/\.(test|spec)\.[jt]sx?$|(^|\/)test_|_test\.py$/.test(f)) {
         namingLabels.push(classifyNaming(base));
+        namingRefs.push(base);
       }
       if (JS_TS_EXTS.has(path.extname(f).toLowerCase())) {
         let src = '';
         try { src = fs.readFileSync(f, 'utf8'); } catch (_) {}
         exportLabels.push(_jsExportStyle(src));
+        exportRefs.push(base);
       }
     }
     return {
-      fileNaming: scoreConvention(namingLabels),
-      exportStyle: scoreConvention(exportLabels),
+      fileNaming: scoreConvention(namingLabels, namingRefs),
+      exportStyle: scoreConvention(exportLabels, exportRefs),
       testFramework: _detectTestFramework(cwd, scoped),
       scope: ['typescript', 'javascript', 'python'],
       scannedFiles: scoped.length,
     };
   }
 
-  module.exports = { classifyNaming, scoreConvention, extractConventions };
+  module.exports = { classifyNaming, scoreConvention, extractConventions };
+  
+};
+
+// ── ./src/conventions/inject ──
+__factories["./src/conventions/inject"] = function(module, exports) {
+  
+  /**
+   * CLAUDE.md convention injection (IMPL.md §7 Phase 2 / §8 step 5).
+   *
+   * Renders the conventions detected by `extractConventions` into a
+   * marker-delimited markdown block and injects it into CLAUDE.md so an agent
+   * reading the file plans grounded in the repo's house style. Idempotent and
+   * marker-scoped — it never touches human content or the `## Auto-generated
+   * signatures` block. Pure string transforms; zero-dependency, bundle-safe.
+   */
+
+  const START = '<!-- sigmap-conventions:start -->';
+  const END = '<!-- sigmap-conventions:end -->';
+
+  const TIER_NOTE = {
+    consistent: 'consistent — match it',
+    mostly: 'dominant, with some drift',
+    inconsistent: 'no clear convention — check neighboring files',
+  };
+
+  const NAMES = {
+    fileNaming: 'File naming',
+    exportStyle: 'Export style',
+  };
+
+  const _pct = (n) => `${Math.round(n * 100)}%`;
+
+  function _conventionLine(label, conv) {
+    if (!conv || conv.total === 0 || !conv.dominant) return null;
+    const note = TIER_NOTE[conv.tier] || conv.tier;
+    let line = `- **${label}:** ${conv.dominant} (${_pct(conv.dominantPct)} — ${note}).`;
+    const others = conv.variants.slice(1).filter((v) => v.pct > 0);
+    if (others.length) {
+      line += ` Variants: ${others.map((v) => `${v.label} ${_pct(v.pct)}`).join(', ')}.`;
+    }
+    return line;
+  }
+
+  /**
+   * Render the conventions block (including its start/end markers).
+   * @param {object} result an `extractConventions` result
+   * @param {string} [version] SigMap version for the footer
+   * @returns {string}
+   */
+  function renderConventionsBlock(result, version) {
+    const lines = [];
+    for (const key of ['fileNaming', 'exportStyle']) {
+      const l = _conventionLine(NAMES[key], result && result[key]);
+      if (l) lines.push(l);
+    }
+    if (result && result.testFramework) {
+      lines.push(`- **Test framework:** ${result.testFramework}.`);
+    }
+
+    const body = lines.length
+      ? lines
+      : ['- No conventions detected yet (run `sigmap conventions` on a TS/JS/Python repo).'];
+
+    const ver = version ? ` v${version}` : '';
+    return [
+      START,
+      '## Conventions (auto-detected by SigMap)',
+      '',
+      'Match these when writing or editing code (TS/JS/Python):',
+      '',
+      ...body,
+      '',
+      `<sub>Generated by SigMap${ver} · run \`sigmap conventions --inject\` to refresh.</sub>`,
+      END,
+    ].join('\n');
+  }
+
+  /**
+   * Inject (or replace) the conventions block in existing CLAUDE.md content.
+   * Replaces an existing marked block in place; appends one when absent.
+   * Idempotent — never touches content outside the markers.
+   * @param {string} existing current file content ('' if the file is new)
+   * @param {string} block the block returned by `renderConventionsBlock`
+   * @returns {string}
+   */
+  function injectConventions(existing, block) {
+    const src = String(existing || '');
+    const startIdx = src.indexOf(START);
+    if (startIdx !== -1) {
+      const endIdx = src.indexOf(END, startIdx);
+      if (endIdx !== -1) {
+        const before = src.slice(0, startIdx);
+        const after = src.slice(endIdx + END.length);
+        return before + block + after;
+      }
+    }
+    if (src.trim() === '') return block + '\n';
+    const sep = src.endsWith('\n') ? '\n' : '\n\n';
+    return src + sep + block + '\n';
+  }
+
+  module.exports = { renderConventionsBlock, injectConventions, START, END };
   
 };
 
-__factories["./src/cache/freshen"] = function(module, exports) {
+// ── ./src/scaffold/propose ──
+__factories["./src/scaffold/propose"] = function(module, exports) {
   
   /**
-   * Read-time self-heal (IMPL.md Layer 1, "safety net" tier).
-   *
-   * Keeps the sig-cache in line with the current source tree so the index reflects
-   * on-disk reality even when no write hook was called. Re-extracts files modified
-   * since the context file was generated (bounded to actual session edits, not the
-   * whole tree), drops cache entries for deleted files, and persists. buildSigIndex
-   * already merges the cache, so the next read is fresh.
-   *
-   * Throttled per cwd. Skips entirely when there is no generated index to heal
-   * (a cold repo should run `generate` or use the notify hooks).
+   * Scaffold proposal with a confidence floor (IMPL.md §5 — Cause 3).
    *
-   * Zero-dependency, bundle-safe (fs + dispatch + sig-cache).
+   * Proposes a convention-matched structure for a new module — filename in the
+   * repo's dominant naming style, the export style to use, and a matching test
+   * file — but only when the conventions are consistent enough. Below a hard
+   * floor it refuses and surfaces the conflict, because a wrong proposal
+   * systematizes bad code. Pure, zero-dependency, bundle-safe; reuses the
+   * conventions primitives.
    */
 
-  const fs = require('fs');
-  const path = require('path');
-  const { loadCache, saveCache, getChangedFiles } = __require('./src/cache/sig-cache');
-  const { extractFile, langFor } = __require('./src/extractors/dispatch');
+  const { toNamingStyle, analyzeConflicts } = __require('./src/conventions/conflicts');
 
-  const DEFAULT_SRC_DIRS = ['src', 'app', 'lib', 'packages', 'services', 'api'];
-  const DEFAULT_EXCLUDE = [
-    'node_modules', '.git', 'dist', 'build', 'out', '__pycache__',
-    '.next', 'coverage', 'target', 'vendor', '.context',
-  ];
-  const CONTEXT_PATHS = [
-    ['.github', 'copilot-instructions.md'],
-    ['CLAUDE.md'], ['AGENTS.md'], ['.github', 'context-cold.md'],
-  ];
-  const THROTTLE_MS = 1500;
-  const _lastRun = new Map();
+  // Soft threshold is configurable; the hard floor is not (IMPL.md §5.1).
+  const DEFAULT_THRESHOLD = 0.7;
+  const HARD_FLOOR = 0.5;
 
-  function _readConfig(cwd) {
-    try {
-      const cfg = JSON.parse(fs.readFileSync(path.join(cwd, 'gen-context.config.json'), 'utf8'));
-      return cfg && typeof cfg === 'object' ? cfg : {};
-    } catch (_) { return {}; }
+  /** Tier for a consistency score (matches the conventions tiers). */
+  function _tier(pct) {
+    if (pct >= 0.9) return 'consistent';
+    if (pct >= 0.7) return 'mostly';
+    return 'inconsistent';
   }
 
-  function _pkgVersion(cwd) {
-    try { return JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8')).version || '0.0.0'; }
-    catch (_) { return '0.0.0'; }
+  /** Strip any extension/compound suffix from a requested name → bare stem. */
+  function _stem(name) {
+    const s = String(name || '').trim();
+    const slash = s.lastIndexOf('/');
+    const base = slash >= 0 ? s.slice(slash + 1) : s;
+    const dot = base.indexOf('.');
+    return dot > 0 ? base.slice(0, dot) : base;
   }
 
-  /** Newest mtime among existing generated context files, or 0 if none. */
-  function _contextMtime(cwd) {
-    let newest = 0;
-    for (const parts of CONTEXT_PATHS) {
-      try { newest = Math.max(newest, fs.statSync(path.join(cwd, ...parts)).mtimeMs); } catch (_) {}
+  /** Test file path for a styled stem given the detected framework + ext. */
+  function _testFile(styledStem, framework, ext) {
+    if (framework === 'pytest' || framework === 'unittest') {
+      return `test_${toNamingStyle(styledStem, 'snake_case')}.py`;
     }
-    return newest;
+    return `${styledStem}.test.${ext}`;
   }
 
-  function _walk(dir, exclude, out, depth, maxDepth) {
-    if (depth > maxDepth) return;
-    let entries;
-    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; }
-    for (const e of entries) {
-      if (exclude.has(e.name)) continue;
-      const full = path.join(dir, e.name);
-      if (e.isDirectory()) _walk(full, exclude, out, depth + 1, maxDepth);
-      else if (e.isFile() && langFor(e.name)) out.push(full);
+  /**
+   * Propose a convention-matched scaffold, gated by a confidence floor.
+   * @param {string} name desired module name (any casing; extension ignored)
+   * @param {object} conventions an `extractConventions` result
+   * @param {object} [opts]
+   * @param {number} [opts.threshold=0.7] soft threshold (clamped to ≥ hard floor)
+   * @param {boolean} [opts.force=false] allow proposing below the soft threshold
+   *   (never below the hard floor)
+   * @param {string} [opts.ext='js'] file extension for the proposed files
+   * @returns {{ ok:boolean, refused:boolean, name:string, tier:string,
+   *   confidence:number, threshold:number, hardFloor:number, forced:boolean,
+   *   warning:string|null, reason:string, proposal:object|null, conflicts:object }}
+   */
+  function proposeScaffold(name, conventions, opts = {}) {
+    const threshold = Math.max(HARD_FLOOR, opts.threshold != null ? opts.threshold : DEFAULT_THRESHOLD);
+    const force = !!opts.force;
+    const ext = opts.ext || 'js';
+    const fileNaming = (conventions && conventions.fileNaming) || { dominant: null, dominantPct: 0, total: 0 };
+    const exportStyle = (conventions && conventions.exportStyle) || { dominant: null };
+    const confidence = fileNaming.dominantPct || 0;
+    const tier = fileNaming.total > 0 ? _tier(confidence) : 'unknown';
+    const conflicts = analyzeConflicts(conventions || {});
+
+    const base = {
+      ok: false, refused: true, name: String(name || ''), tier, confidence,
+      threshold, hardFloor: HARD_FLOOR, forced: false, warning: null,
+      reason: '', proposal: null, conflicts,
+    };
+
+    if (!fileNaming.dominant || fileNaming.total === 0) {
+      return { ...base, reason: 'no file-naming convention detected — cannot propose a name' };
+    }
+    if (confidence < HARD_FLOOR) {
+      return {
+        ...base,
+        reason: `file-naming consistency ${(confidence * 100).toFixed(0)}% is below the hard floor ${(HARD_FLOOR * 100).toFixed(0)}% — refusing (not overridable)`,
+      };
+    }
+    if (confidence < threshold && !force) {
+      return {
+        ...base,
+        reason: `file-naming consistency ${(confidence * 100).toFixed(0)}% is below the threshold ${(threshold * 100).toFixed(0)}% — refusing (use --force to override above the ${(HARD_FLOOR * 100).toFixed(0)}% floor)`,
+      };
     }
+
+    const styledStem = toNamingStyle(_stem(name), fileNaming.dominant);
+    const forced = confidence < threshold && force;
+    const proposal = {
+      filename: `${styledStem}.${ext}`,
+      namingStyle: fileNaming.dominant,
+      exportStyle: exportStyle.dominant || 'named',
+      testFile: _testFile(styledStem, conventions.testFramework, ext),
+      testFramework: conventions.testFramework || null,
+    };
+
+    return {
+      ...base,
+      ok: true,
+      refused: false,
+      forced,
+      warning: forced
+        ? `proposed below the ${(threshold * 100).toFixed(0)}% threshold (--force); conventions are only ${tier}`
+        : null,
+      reason: forced ? 'forced proposal above the hard floor' : `conventions are ${tier} — proposing`,
+      proposal,
+    };
   }
 
+  module.exports = { proposeScaffold, DEFAULT_THRESHOLD, HARD_FLOOR };
+  
+};
+
+__factories["./src/plan/verify-plan"] = function(module, exports) {
+  
   /**
-   * Re-extract source files changed since the last generate; drop deleted files.
-   * @param {string} cwd
-   * @param {{force?:boolean, now?:number}} [opts]
-   * @returns {number} cache entries touched
+   * verify-plan (IMPL.md §6.1 — Gap 2, step 2 of the `create` pipeline).
+   *
+   * Checks a plan (markdown) against the LIVE index before execution: do the
+   * referenced files and symbols exist, is the blast radius acceptable, is the
+   * scope in bounds? Catches Cause 1+2 at plan time — cheaper than after the
+   * code is written. Reuses the verify primitives + the impact graph.
+   * Zero-dependency, bundle-safe.
    */
-  function freshen(cwd, opts = {}) {
-    const now = opts.now != null ? opts.now : Date.now();
-    if (!opts.force) {
-      if (now - (_lastRun.get(cwd) || 0) < THROTTLE_MS) return 0;
-    }
-    _lastRun.set(cwd, now);
 
-    try {
-      const version = _pkgVersion(cwd);
-      const cache = loadCache(cwd, version);
-      const ctxMtime = _contextMtime(cwd);
-      // Nothing to heal: no generated context AND no live cache overlay.
-      if (ctxMtime === 0 && cache.size === 0) return 0;
+  const fs = require('fs');
+  const path = require('path');
+  const { extractFilePaths, extractSymbols } = __require('./src/verify/parsers');
+  const { buildSymbolSet } = __require('./src/verify/hallucination-guard');
+  const { closestMatch } = __require('./src/verify/closest-match');
+  const { analyzeImpact } = __require('./src/graph/impact');
 
-      const cfg = _readConfig(cwd);
-      const srcDirs = Array.isArray(cfg.srcDirs) && cfg.srcDirs.length ? cfg.srcDirs : DEFAULT_SRC_DIRS;
-      const exclude = new Set([...DEFAULT_EXCLUDE, ...(Array.isArray(cfg.exclude) ? cfg.exclude : [])]);
-      const maxDepth = Number.isFinite(cfg.maxDepth) ? cfg.maxDepth : 8;
+  const DEFAULT_BLAST_THRESHOLD = 20; // transitive+direct dependents → "high blast radius"
+  const DEFAULT_SCOPE_THRESHOLD = 10; // distinct referenced files → "broad scope"
 
-      const files = [];
-      for (const d of srcDirs) {
-        const abs = path.isAbsolute(d) ? d : path.join(cwd, d);
-        if (fs.existsSync(abs)) _walk(abs, exclude, files, 0, maxDepth);
-      }
+  /** Resolve a referenced path against cwd (handles a leading "./"). */
+  function _fileExists(cwd, ref) {
+    const clean = ref.replace(/^\.\//, '');
+    for (const c of [path.resolve(cwd, clean), path.resolve(cwd, ref)]) {
+      try { if (fs.existsSync(c)) return true; } catch (_) {}
+    }
+    return false;
+  }
 
-      // Candidates = files modified since the context was generated, or not yet cached.
-      const candidates = files.filter((f) => {
-        try { return fs.statSync(f).mtimeMs > ctxMtime || !cache.has(f); } catch (_) { return false; }
+  /**
+   * Verify a plan against the live index.
+   * @param {string} planText the plan as markdown
+   * @param {string} cwd repo root
+   * @param {object} [opts]
+   * @param {number} [opts.blastThreshold=20]
+   * @param {number} [opts.scopeThreshold=10]
+   * @param {(ref:string)=>boolean} [opts.fileExists] override for testing
+   * @returns {{ issues: object[], blast: object[], scope: object, summary: object }}
+   */
+  function verifyPlan(planText, cwd, opts = {}) {
+    const blastThreshold = opts.blastThreshold != null ? opts.blastThreshold : DEFAULT_BLAST_THRESHOLD;
+    const scopeThreshold = opts.scopeThreshold != null ? opts.scopeThreshold : DEFAULT_SCOPE_THRESHOLD;
+    const fileExists = opts.fileExists || ((ref) => _fileExists(cwd, ref));
+
+    const text = String(planText || '');
+    const filesRef = extractFilePaths(text);   // [{ path, line }]
+    const symbolsRef = extractSymbols(text);   // [{ name, line }]
+    const { set: symbolSet, symbolCandidates } = buildSymbolSet(cwd);
+
+    const issues = [];
+
+    // 1. Referenced files must exist.
+    const existingFiles = [];
+    for (const f of filesRef) {
+      if (fileExists(f.path)) existingFiles.push(f.path);
+      else issues.push({ type: 'missing-file', ref: f.path, line: f.line, severity: 'error' });
+    }
+
+    // 2. Referenced symbols must exist in the live index (suggest a near match).
+    for (const s of symbolsRef) {
+      if (symbolSet.has(s.name)) continue;
+      const match = closestMatch(s.name, symbolCandidates);
+      issues.push({
+        type: 'unknown-symbol', ref: s.name, line: s.line, severity: 'error',
+        suggestion: match ? match.name : null,
       });
-      const { changed } = getChangedFiles(candidates, cache);
+    }
 
-      let touched = 0;
-      for (const f of changed) {
-        try {
-          const sigs = extractFile(f, fs.readFileSync(f, 'utf8'));
-          cache.set(f, { mtime: fs.statSync(f).mtimeMs, sigs });
-          touched++;
-        } catch (_) {}
+    // 3. Blast radius for each existing referenced file (one graph build).
+    const blast = [];
+    if (existingFiles.length) {
+      let impacts = [];
+      try { impacts = analyzeImpact(existingFiles, cwd, {}); } catch (_) { impacts = []; }
+      for (const { file, impact } of impacts) {
+        const entry = { file, totalImpact: impact.totalImpact, tests: impact.tests.length };
+        blast.push(entry);
+        if (impact.totalImpact > blastThreshold) {
+          issues.push({ type: 'high-blast-radius', ref: file, count: impact.totalImpact, severity: 'warn' });
+        }
       }
-      // Note: deletions are NOT swept here — a cache entry may be a `notify`
-      // overlay for a file not yet on disk. Explicit removal is `notify_file_deleted`.
+      blast.sort((a, b) => b.totalImpact - a.totalImpact);
+    }
 
-      if (touched > 0) saveCache(cwd, version, cache);
-      return touched;
-    } catch (_) {
-      return 0;
+    // 4. Scope.
+    const scope = { files: filesRef.length, symbols: symbolsRef.length, threshold: scopeThreshold };
+    if (filesRef.length > scopeThreshold) {
+      issues.push({ type: 'broad-scope', count: filesRef.length, threshold: scopeThreshold, severity: 'warn' });
     }
+
+    const errors = issues.filter((i) => i.severity === 'error').length;
+    const warnings = issues.filter((i) => i.severity === 'warn').length;
+    return {
+      issues,
+      blast,
+      scope,
+      summary: {
+        filesReferenced: filesRef.length,
+        symbolsReferenced: symbolsRef.length,
+        errors,
+        warnings,
+        ok: errors === 0,
+      },
+    };
   }
 
-  module.exports = { freshen };
+  module.exports = { verifyPlan, DEFAULT_BLAST_THRESHOLD, DEFAULT_SCOPE_THRESHOLD };
   
 };
+
 // ── ./src/extractors/dispatch ──
 __factories["./src/extractors/dispatch"] = function(module, exports) {
   
@@ -7119,7 +7369,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
 
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '7.10.0',
+    version: '7.12.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
 
@@ -12797,7 +13047,7 @@ function __tryGit(args, opts = {}) {
   catch (_) { return ''; }
 }
 
-const VERSION = '7.10.0';
+const VERSION = '7.12.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -16151,6 +16401,47 @@ function main() {
   }
 
   // `sigmap verify-ai-output <answer.md>` — Hallucination Guard (deterministic core)
+  // Gap 2 (step 2): `sigmap verify-plan <plan.md>` — check a plan against the
+  // live index before execution (files/symbols exist, blast radius, scope).
+  if (args[0] === 'verify-plan') {
+    const target = args[1] && !args[1].startsWith('--') ? args[1] : null;
+    const jsonOut = args.includes('--json');
+    if (!target) {
+      console.error('[sigmap] Usage: sigmap verify-plan <plan.md|-> [--json]');
+      process.exit(1);
+    }
+    let planText = '';
+    try {
+      planText = fs.readFileSync(target === '-' ? 0 : path.resolve(cwd, target), 'utf8');
+    } catch (e) {
+      console.error(`[sigmap] cannot read plan: ${e.message}`);
+      process.exit(1);
+    }
+    const { verifyPlan } = requireSourceOrBundled('./src/plan/verify-plan');
+    const result = verifyPlan(planText, cwd);
+
+    if (jsonOut) {
+      process.stdout.write(JSON.stringify(result) + '\n');
+      process.exit(result.summary.ok ? 0 : 1);
+    }
+
+    const s = result.summary;
+    console.log(`[sigmap] verify-plan — ${s.filesReferenced} file(s), ${s.symbolsReferenced} symbol(s) referenced`);
+    if (result.issues.length === 0) {
+      console.log('  ✓ plan checks out — all references exist, blast radius and scope in bounds');
+      process.exit(0);
+    }
+    for (const i of result.issues) {
+      const mark = i.severity === 'error' ? '✗' : '⚠';
+      if (i.type === 'missing-file') console.log(`  ${mark} missing file: ${i.ref} (line ${i.line})`);
+      else if (i.type === 'unknown-symbol') console.log(`  ${mark} unknown symbol: ${i.ref}()${i.suggestion ? ` — did you mean ${i.suggestion}()?` : ''} (line ${i.line})`);
+      else if (i.type === 'high-blast-radius') console.log(`  ${mark} high blast radius: ${i.ref} → ${i.count} dependents`);
+      else if (i.type === 'broad-scope') console.log(`  ${mark} broad scope: ${i.count} files (threshold ${i.threshold})`);
+    }
+    console.log(`\n  ${s.errors} error(s), ${s.warnings} warning(s)`);
+    process.exit(s.ok ? 0 : 1);
+  }
+
   if (args[0] === 'verify-ai-output') {
     const target = args[1];
     const jsonOut = args.includes('--json');
@@ -16208,6 +16499,60 @@ function main() {
     process.exit(1);
   }
 
+  // Gap 2 (step 4): `sigmap review-pr` — diff audit (scope drift, god-nodes,
+  // missing tests, security-sensitive files). Last guard stage of `create`.
+  if (args[0] === 'review-pr') {
+    const jsonOut = args.includes('--json');
+    const staged = args.includes('--staged');
+    const baseIdx = args.indexOf('--base');
+    const baseArg = baseIdx !== -1 && args[baseIdx + 1] && !args[baseIdx + 1].startsWith('--') ? args[baseIdx + 1] : null;
+
+    let nameStatus = '';
+    if (staged) {
+      nameStatus = __tryGit(['diff', '--cached', '--name-status'], { cwd });
+    } else {
+      let base = baseArg;
+      if (!base) {
+        for (const ref of ['main', 'develop']) {
+          if (__tryGit(['rev-parse', '--verify', '--quiet', ref], { cwd })) { base = ref; break; }
+        }
+      }
+      const mb = base ? (__tryGit(['merge-base', 'HEAD', base], { cwd }) || base) : 'HEAD~1';
+      nameStatus = __tryGit(['diff', '--name-status', `${mb}..HEAD`], { cwd });
+    }
+
+    const changedFiles = nameStatus.split('\n').filter(Boolean).map((line) => {
+      const parts = line.split('\t');
+      const status = parts[0][0]; // M/A/D/R…
+      const file = parts[parts.length - 1]; // rename → new path
+      return { path: file, status };
+    });
+
+    const { reviewPr } = requireSourceOrBundled('./src/review/review-pr');
+    const result = reviewPr(changedFiles, cwd, {});
+
+    if (jsonOut) {
+      process.stdout.write(JSON.stringify(result) + '\n');
+      process.exit(result.summary.ok ? 0 : 1);
+    }
+
+    const s = result.summary;
+    console.log(`[sigmap] review-pr — ${s.filesChanged} file(s) changed (${s.sourceChanged} source, ${s.testsChanged} test)`);
+    if (s.findings === 0) {
+      console.log('  ✓ no findings — scope, tests, blast radius, and sensitive files all clear');
+      process.exit(0);
+    }
+    const label = { 'missing-tests': 'missing tests', 'security-file': 'security file', 'god-node': 'god node', 'scope-drift': 'scope drift' };
+    for (const f of result.findings) {
+      if (f.type === 'missing-tests') console.log(`  ⚠ ${label[f.type]}: ${f.file} changed with no matching test`);
+      else if (f.type === 'security-file') console.log(`  ⚠ ${label[f.type]}: ${f.file}`);
+      else if (f.type === 'god-node') console.log(`  ⚠ ${label[f.type]}: ${f.file} → ${f.count} dependents`);
+      else if (f.type === 'scope-drift') console.log(`  ⚠ ${label[f.type]}: ${f.count} top-level dirs (${f.dirs.join(', ')})`);
+    }
+    console.log(`\n  ${s.findings} finding(s)`);
+    process.exit(1);
+  }
+
   // Feature 1: `sigmap explain <file>` — why a file is included or excluded
   if (args[0] === 'explain' || args.includes('--explain')) {
     const target = args[0] === 'explain'