sigmap 7.8.0 → 7.10.0

package/CHANGELOG.md

@@ -10,6 +10,24 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [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).
+
+### Added
+- **`sigmap conventions --inject` — write the conventions block into CLAUDE.md (#304):** the next slice of Layer 3, completing the "agent sees the house style" link in the grounded-creation loop. Renders the detected conventions (file naming, export style, test framework — each with its dominant pattern and consistency tier) into a marker-delimited block and injects it into `CLAUDE.md`, creating the file if absent. New zero-dependency, bundle-safe `src/conventions/inject.js` (`renderConventionsBlock`, `injectConventions`): the injection is idempotent and marker-scoped (`<!-- sigmap-conventions:start -->` … `:end -->`), preserving all human content and coexisting with the existing `## Auto-generated signatures` block. `--report`, `--fix`, `--update`, `--ci`, and Layer 4 scaffold remain follow-ups.
+
+---
+
 ## [7.8.0] — 2026-06-17
 
 Minor release — `sigmap conventions --conflicts` (grounded codegen, Layer 3).

package/gen-context.js

@@ -23,6 +23,224 @@ function __require(key) {
 // ── ./src/cache/freshen ──
 // ── ./src/conventions/extract ──
 // ── ./src/conventions/conflicts ──
+// ── ./src/conventions/inject ──
+// ── ./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}`;
+  }
+
+  /**
+   * 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/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/conventions/conflicts"] = function(module, exports) {
   
   /**
@@ -6901,7 +7119,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
 
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '7.8.0',
+    version: '7.10.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
 
@@ -12579,7 +12797,7 @@ function __tryGit(args, opts = {}) {
   catch (_) { return ''; }
 }
 
-const VERSION = '7.8.0';
+const VERSION = '7.10.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -15757,6 +15975,23 @@ function main() {
     const files = buildFileList(cwd, config);
     const result = extractConventions(cwd, files);
 
+    // `--inject`: write/update the conventions block in CLAUDE.md (idempotent).
+    if (args.includes('--inject')) {
+      const { renderConventionsBlock, injectConventions } = requireSourceOrBundled('./src/conventions/inject');
+      const claudePath = path.join(cwd, 'CLAUDE.md');
+      let existing = '';
+      try { if (fs.existsSync(claudePath)) existing = fs.readFileSync(claudePath, 'utf8'); } catch (_) {}
+      const block = renderConventionsBlock(result, VERSION);
+      try {
+        fs.writeFileSync(claudePath, injectConventions(existing, block));
+      } catch (e) {
+        console.error(`[sigmap] cannot write ${claudePath}: ${e.message}`);
+        process.exit(1);
+      }
+      console.log(`[sigmap] conventions → injected block into ${path.relative(cwd, claudePath) || 'CLAUDE.md'}`);
+      process.exit(0);
+    }
+
     // `--conflicts`: surface why a convention is mixed (breakdown + rename suggestions).
     if (args.includes('--conflicts')) {
       const { analyzeConflicts } = requireSourceOrBundled('./src/conventions/conflicts');
@@ -15822,6 +16057,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');

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.8.0 | Benchmark: sigmap-v7.0-main (2026-06-14)
+# Version: 7.10.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.8.0 | Benchmark: sigmap-v7.0-main (2026-06-14)
+# Version: 7.10.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.8.0",
+  "version": "7.10.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.8.0",
+  "version": "7.10.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.8.0",
+  "version": "7.10.0",
   "description": "SigMap core library — zero-dependency code signature extraction, retrieval, and security scanning",
   "main": "index.js",
   "keywords": [

package/src/conventions/inject.js

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * 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 };

package/src/mcp/server.js

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

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 };