sigmap 7.9.0 → 7.11.0

package/CHANGELOG.md

@@ -10,6 +10,24 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [7.11.0] — 2026-06-17
+
+Minor release — `sigmap verify-plan` (grounded codegen, Gap 2).
+
+### Added
+- **`sigmap verify-plan <plan.md>` — check a plan against the live index (#310):** the first piece of the `sigmap create` pipeline (Gap 2, step 2). Before an agent executes a plan, `verify-plan` validates it against the live index — referenced files and symbols exist, blast radius is acceptable, scope is in bounds — catching Cause 1+2 at plan time (cheaper than after the code is written). New zero-dependency, bundle-safe `src/plan/verify-plan.js` (`verifyPlan`): flags missing files and unknown symbols (with closest-match suggestions), computes per-file blast radius via the impact graph (flags high-blast-radius files), and flags broad scope. Plan input schema is **markdown** (consistent with `verify-ai-output`). CLI reads a file or stdin (`-`), supports `--json`, and exits 1 on blocking errors. The `sigmap create` orchestration and `review-pr` remain follow-ups.
+
+---
+
+## [7.10.0] — 2026-06-17
+
+Minor release — `sigmap scaffold` with a confidence floor (grounded codegen, Layer 4).
+
+### Added
+- **`sigmap scaffold <name>` — convention-matched proposal with a confidence floor (#307):** the first slice of Layer 4 (Cause 3 — guessing structure for new code). 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**. New zero-dependency, bundle-safe `src/scaffold/propose.js` (`proposeScaffold`): the governing confidence is file-naming consistency, with a soft threshold (default 0.70, overridable via `--threshold`) and a **non-overridable hard floor of 0.50**. Below the threshold it refuses and surfaces the conflict (reusing `analyzeConflicts`); `--force` allows a proposal between the floor and the threshold (flagged with a warning), but never below the floor — a wrong proposal systematizes bad code. CLI supports `--ext`, `--threshold`, `--force`, and `--json` (refusal exits 1). Scaffold persistence (`.sigmap/scaffold/latest.md`), `--naming-pattern` override, and the `verify-plan` → `create` → `review-pr` pipeline remain follow-ups.
+
+---
+
 ## [7.9.0] — 2026-06-17
 
 Minor release — `sigmap conventions --inject` (grounded codegen, Layer 3).

package/gen-context.js

@@ -24,107 +24,136 @@ function __require(key) {
 // ── ./src/conventions/extract ──
 // ── ./src/conventions/conflicts ──
 // ── ./src/conventions/inject ──
-__factories["./src/conventions/inject"] = function(module, exports) {
+// ── ./src/scaffold/propose ──
+// ── ./src/plan/verify-plan ──
+// ── ./src/cache/freshen ──
+__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) {
   
   /**
@@ -239,6 +268,7 @@ __factories["./src/conventions/conflicts"] = function(module, exports) {
   
 };
 
+// ── ./src/conventions/extract ──
 __factories["./src/conventions/extract"] = function(module, exports) {
   
   /**
@@ -283,24 +313,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';
@@ -372,22 +420,26 @@ __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,
@@ -398,131 +450,335 @@ __factories["./src/conventions/extract"] = function(module, exports) {
   
 };
 
-__factories["./src/cache/freshen"] = function(module, exports) {
+// ── ./src/conventions/inject ──
+__factories["./src/conventions/inject"] = 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).
+   * CLAUDE.md convention injection (IMPL.md §7 Phase 2 / §8 step 5).
    *
-   * Zero-dependency, bundle-safe (fs + dispatch + sig-cache).
+   * 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 fs = require('fs');
-  const path = require('path');
-  const { loadCache, saveCache, getChangedFiles } = __require('./src/cache/sig-cache');
-  const { extractFile, langFor } = __require('./src/extractors/dispatch');
+  const START = '<!-- sigmap-conventions:start -->';
+  const END = '<!-- sigmap-conventions:end -->';
 
-  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 TIER_NOTE = {
+    consistent: 'consistent — match it',
+    mostly: 'dominant, with some drift',
+    inconsistent: 'no clear convention — check neighboring files',
+  };
 
-  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 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;
   }
 
-  function _pkgVersion(cwd) {
-    try { return JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8')).version || '0.0.0'; }
-    catch (_) { return '0.0.0'; }
+  /**
+   * 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');
   }
 
-  /** 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 (_) {}
+  /**
+   * 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;
+      }
     }
-    return newest;
+    if (src.trim() === '') return block + '\n';
+    const sep = src.endsWith('\n') ? '\n' : '\n\n';
+    return src + sep + block + '\n';
   }
 
-  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);
+  module.exports = { renderConventionsBlock, injectConventions, START, END };
+  
+};
+
+// ── ./src/scaffold/propose ──
+__factories["./src/scaffold/propose"] = function(module, exports) {
+  
+  /**
+   * Scaffold proposal with a confidence floor (IMPL.md §5 — Cause 3).
+   *
+   * 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 { 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;
+
+  /** 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';
+  }
+
+  /** 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;
+  }
+
+  /** 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}`;
   }
 
   /**
-   * 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
+   * 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 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;
+  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)`,
+      };
     }
-    _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 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,
+    };
 
-      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;
+    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,
+    };
+  }
 
-      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);
-      }
+  module.exports = { proposeScaffold, DEFAULT_THRESHOLD, HARD_FLOOR };
+  
+};
 
-      // 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; }
+__factories["./src/plan/verify-plan"] = function(module, exports) {
+  
+  /**
+   * 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.
+   */
+
+  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 DEFAULT_BLAST_THRESHOLD = 20; // transitive+direct dependents → "high blast radius"
+  const DEFAULT_SCOPE_THRESHOLD = 10; // distinct referenced files → "broad scope"
+
+  /** 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;
+  }
+
+  /**
+   * 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) {
   
@@ -7003,7 +7259,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
 
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '7.9.0',
+    version: '7.11.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
 
@@ -12681,7 +12937,7 @@ function __tryGit(args, opts = {}) {
   catch (_) { return ''; }
 }
 
-const VERSION = '7.9.0';
+const VERSION = '7.11.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -15941,6 +16197,56 @@ function main() {
     process.exit(0);
   }
 
+  // Layer 4: `sigmap scaffold <name>` — propose a convention-matched structure
+  // for a new module, gated by a confidence floor (refuses if conventions are
+  // too inconsistent; a wrong proposal systematizes bad code).
+  if (args[0] === 'scaffold') {
+    const jsonOut = args.includes('--json');
+    const name = args[1] && !args[1].startsWith('--') ? args[1] : null;
+    if (!name) {
+      console.error('[sigmap] usage: sigmap scaffold <name> [--ext <e>] [--threshold <n>] [--force] [--json]');
+      process.exit(1);
+    }
+    const thIdx = args.indexOf('--threshold');
+    const threshold = thIdx !== -1 && args[thIdx + 1] ? parseFloat(args[thIdx + 1]) : undefined;
+    const extIdx = args.indexOf('--ext');
+    const ext = extIdx !== -1 && args[extIdx + 1] ? args[extIdx + 1].replace(/^\./, '') : undefined;
+    const force = args.includes('--force');
+
+    const { extractConventions } = requireSourceOrBundled('./src/conventions/extract');
+    const { proposeScaffold } = requireSourceOrBundled('./src/scaffold/propose');
+    const conventions = extractConventions(cwd, buildFileList(cwd, config));
+    const decision = proposeScaffold(name, conventions, { threshold, ext, force });
+
+    if (jsonOut) {
+      process.stdout.write(JSON.stringify(decision) + '\n');
+      process.exit(decision.ok ? 0 : 1);
+    }
+
+    const pctS = (n) => `${(n * 100).toFixed(0)}%`;
+    if (decision.ok) {
+      console.log(`[sigmap] scaffold "${decision.name}"  — conventions ${decision.tier} (${pctS(decision.confidence)})`);
+      if (decision.warning) console.log(`  ⚠ ${decision.warning}`);
+      const p = decision.proposal;
+      console.log(`  file:           ${p.filename}  (${p.namingStyle})`);
+      console.log(`  export style:   ${p.exportStyle}`);
+      console.log(`  test file:      ${p.testFile}${p.testFramework ? `  (${p.testFramework})` : ''}`);
+      process.exit(0);
+    }
+
+    console.log(`[sigmap] scaffold "${decision.name}" — REFUSED`);
+    console.log(`  ${decision.reason}`);
+    if (decision.conflicts && decision.conflicts.hasConflicts) {
+      for (const c of decision.conflicts.conventions) {
+        console.log(`\n  ${c.name} — dominant: ${c.dominant} ${pctS(c.dominantPct)} [${c.tier}]`);
+        for (const v of c.variants) {
+          console.log(`    ${v.pattern.padEnd(12)} ${pctS(v.pct).padStart(4)}${v.examples.length ? `  e.g. ${v.examples.join(', ')}` : ''}`);
+        }
+      }
+    }
+    process.exit(1);
+  }
+
   // v7.0.0: `sigmap squeeze <file|->` — minimize a pasted stacktrace / CI-log / JSON blob
   if (args[0] === 'squeeze') {
     const jsonOut = args.includes('--json');
@@ -15985,6 +16291,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');

package/llms-full.txt

@@ -9,7 +9,7 @@ the files relevant to the task — cutting tokens ~97% while keeping answers
 grounded. Deterministic, offline, no embeddings or vector database. Works with
 Claude, Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 7.9.0 | Benchmark: sigmap-v7.0-main (2026-06-14)
+# Version: 7.11.0 | Benchmark: sigmap-v7.0-main (2026-06-14)
 # Source: auto-generated from package.json, version.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 

package/llms.txt

@@ -9,7 +9,7 @@ the files relevant to the task — cutting tokens ~97% while keeping answers
 grounded. Deterministic, offline, no embeddings or vector database. Works with
 Claude, Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 7.9.0 | Benchmark: sigmap-v7.0-main (2026-06-14)
+# Version: 7.11.0 | Benchmark: sigmap-v7.0-main (2026-06-14)
 # Source: auto-generated from package.json, version.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "7.9.0",
+  "version": "7.11.0",
   "description": "97% token reduction for AI coding. Extracts function & class signatures with TF-IDF ranking to feed only the right files to Claude, Cursor, Copilot, Aider, Windsurf, local LLMs & MCP. Zero dependencies, runs offline via npx.",
   "main": "packages/core/index.js",
   "exports": {

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-cli",
-  "version": "7.9.0",
+  "version": "7.11.0",
   "description": "SigMap CLI wrapper — thin adapter for programmatic CLI invocation",
   "main": "index.js",
   "keywords": [

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-core",
-  "version": "7.9.0",
+  "version": "7.11.0",
   "description": "SigMap core library — zero-dependency code signature extraction, retrieval, and security scanning",
   "main": "index.js",
   "keywords": [

package/src/mcp/server.js

@@ -18,7 +18,7 @@ const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, exp
 
 const SERVER_INFO = {
   name: 'sigmap',
-  version: '7.9.0',
+  version: '7.11.0',
   description: 'SigMap MCP server — code signatures on demand',
 };
 

package/src/plan/verify-plan.js

@@ -0,0 +1,108 @@
+'use strict';
+
+/**
+ * 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.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { extractFilePaths, extractSymbols } = require('../verify/parsers');
+const { buildSymbolSet } = require('../verify/hallucination-guard');
+const { closestMatch } = require('../verify/closest-match');
+const { analyzeImpact } = require('../graph/impact');
+
+const DEFAULT_BLAST_THRESHOLD = 20; // transitive+direct dependents → "high blast radius"
+const DEFAULT_SCOPE_THRESHOLD = 10; // distinct referenced files → "broad scope"
+
+/** 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;
+}
+
+/**
+ * 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,
+    });
+  }
+
+  // 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' });
+      }
+    }
+    blast.sort((a, b) => b.totalImpact - a.totalImpact);
+  }
+
+  // 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 = { verifyPlan, DEFAULT_BLAST_THRESHOLD, DEFAULT_SCOPE_THRESHOLD };

package/src/scaffold/propose.js

@@ -0,0 +1,112 @@
+'use strict';
+
+/**
+ * Scaffold proposal with a confidence floor (IMPL.md §5 — Cause 3).
+ *
+ * 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 { toNamingStyle, analyzeConflicts } = require('../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;
+
+/** 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';
+}
+
+/** 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;
+}
+
+/** 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}`;
+}
+
+/**
+ * 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 };