@geraldmaron/construct 1.0.6 → 1.0.7

package/lib/hooks/proactive-activation.mjs

@@ -239,20 +239,6 @@ export function onScheduleCheck() {
   return events;
 }
 
-/**
- * Get all pending activations for a specialist.
- */
-export function getPendingActivations(specialist) {
-  // In a full implementation, this would query a pending queue
-  // For now, return recent activation history
-  const state = getActivationState(specialist);
-  return {
-    pending: 0,
-    recent: state.activations.length,
-    total: state.totalActivations,
-  };
-}
-
 /**
  * Clear activation state (for testing or manual reset).
  */

package/lib/hooks/rule-verifier.mjs

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/rule-verifier.mjs — Stop hook that audits the session for
+ * compliance with the construct rules the agent claimed to follow.
+ *
+ * Checks:
+ *   - Each commit / push was preceded by an approval signal scoped to that
+ *     branch + change.
+ *   - Edits to protected files (CLAUDE.md table) had user confirmation.
+ *   - Beads claims exist for any work that touched durable state.
+ *
+ * Approval detection is intent-based, not keyword-based. The verifier reads
+ * the conversational window before each consequential action and classifies
+ * the user's stance: APPROVED, REFUSED, INCONCLUSIVE. Direct affirmation,
+ * accepting a proposed plan that named the action, or "go ahead" all count
+ * as approval — no specific word is required.
+ *
+ * Output: { ok: 'pass' | 'fail' | 'inconclusive', findings[] } written to
+ * .cx/audit.jsonl. Inconclusive results surface as escalation questions to
+ * the user rather than silent passes or false-positive blocks.
+ *
+ * @p95ms 200
+ * @maxBlockingScope Stop
+ */
+
+import { readFileSync, existsSync, appendFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { logHookFailure } from './_lib/log.mjs';
+
+const AUDIT_REL = '.cx/audit.jsonl';
+
+function safeReadJsonLines(transcriptPath) {
+  try {
+    const raw = readFileSync(transcriptPath, 'utf8');
+    return raw.split('\n').map((line) => { try { return JSON.parse(line); } catch { return null; } }).filter(Boolean);
+  } catch { return []; }
+}
+
+function lastN(entries, count) {
+  return entries.slice(Math.max(0, entries.length - count));
+}
+
+/**
+ * Identify consequential actions in the transcript tail. Returns a list of
+ * { kind, branch, target, atIndex } items. Each one needs an approval signal
+ * within the window of conversation immediately preceding it.
+ *
+ * Detected actions:
+ *   - 'commit'        — git commit invocation
+ *   - 'push'          — git push invocation
+ *   - 'protected'     — edit to a CLAUDE.md-protected file
+ *   - 'durable-state' — bd close / claim against durable state
+ */
+export function findConsequentialActions(entries) {
+  const actions = [];
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    const cmd = extractBashCommand(e);
+    if (cmd) {
+      if (/^git\s+commit\b/.test(cmd) && !/--dry-run/.test(cmd)) {
+        actions.push({ kind: 'commit', target: cmd.slice(0, 200), atIndex: i });
+      } else if (/^git\s+push\b/.test(cmd) && !/--dry-run/.test(cmd)) {
+        actions.push({ kind: 'push', target: cmd.slice(0, 200), atIndex: i });
+      } else if (/^gh\s+pr\s+(create|merge)\b/.test(cmd)) {
+        actions.push({ kind: 'pr-mutation', target: cmd.slice(0, 200), atIndex: i });
+      }
+    }
+    const editPath = extractEditPath(e);
+    if (editPath && /CLAUDE\.md|install\.sh|claude\/settings\.template\.json|agents\/registry\.json/.test(editPath)) {
+      actions.push({ kind: 'protected', target: editPath, atIndex: i });
+    }
+  }
+  return actions;
+}
+
+function extractBashCommand(entry) {
+  const toolUse = entry?.message?.content?.find?.((c) => c?.type === 'tool_use' && c?.name === 'Bash');
+  return toolUse?.input?.command || null;
+}
+
+function extractEditPath(entry) {
+  const toolUse = entry?.message?.content?.find?.((c) => c?.type === 'tool_use' && (c?.name === 'Edit' || c?.name === 'Write'));
+  return toolUse?.input?.file_path || null;
+}
+
+/**
+ * Classify a conversational window for approval intent. This is intentionally
+ * conservative — it does not require any keyword. If the window contains a
+ * user turn that directly addresses the action being taken (mentioning the
+ * branch, the file, or accepting a proposed plan), that counts as approval.
+ *
+ * The default classifier is deterministic: it scans for plausible approval
+ * tokens AND for the action target appearing earlier in the conversation.
+ * A pluggable classifier can replace this with an LLM-graded inference at
+ * runtime — register via setApprovalClassifier(fn).
+ *
+ * Returns: 'APPROVED' | 'REFUSED' | 'INCONCLUSIVE'.
+ */
+let _approvalClassifier = defaultApprovalClassifier;
+
+export function setApprovalClassifier(fn) {
+  _approvalClassifier = typeof fn === 'function' ? fn : defaultApprovalClassifier;
+}
+
+export function classifyApproval(window, action) {
+  return _approvalClassifier(window, action);
+}
+
+function defaultApprovalClassifier(window, action) {
+  if (!Array.isArray(window) || window.length === 0) return 'INCONCLUSIVE';
+
+  let assistantProposedAction = false;
+  let userResponded = false;
+  let userRefused = false;
+  let userAffirmed = false;
+
+  for (const entry of window) {
+    const role = entry?.message?.role || entry?.role;
+    const text = extractText(entry).toLowerCase();
+    if (!text) continue;
+
+    if (role === 'assistant') {
+      if (actionMentioned(text, action)) assistantProposedAction = true;
+    }
+    if (role === 'user') {
+      userResponded = true;
+      if (/\b(no|stop|don'?t|cancel|wait|abort|hold off|never mind)\b/.test(text)) userRefused = true;
+      if (/\b(yes|yep|yeah|go ahead|do it|proceed|ship it|approve|confirmed|sounds good|that works|lgtm|sgtm|ok|sure|please do|merge it|continue)\b/.test(text)) userAffirmed = true;
+      // Even without explicit affirmation words, accepting a named plan is approval.
+      if (assistantProposedAction && !userRefused && text.length > 0 && !/\?$/.test(text.trim())) {
+        userAffirmed = userAffirmed || /\b(thanks|great|perfect|sounds|works|good)\b/.test(text);
+      }
+    }
+  }
+
+  if (userRefused) return 'REFUSED';
+  if (userAffirmed && assistantProposedAction) return 'APPROVED';
+  if (userAffirmed) return 'APPROVED';
+  if (!userResponded) return 'INCONCLUSIVE';
+  return 'INCONCLUSIVE';
+}
+
+function extractText(entry) {
+  const msg = entry?.message;
+  if (!msg) return '';
+  if (typeof msg.content === 'string') return msg.content;
+  if (Array.isArray(msg.content)) {
+    return msg.content.map((c) => (typeof c === 'string' ? c : c?.text || '')).join(' ');
+  }
+  return '';
+}
+
+function actionMentioned(text, action) {
+  if (!text) return false;
+  if (action.kind === 'commit' || action.kind === 'push' || action.kind === 'pr-mutation') {
+    return /\b(commit|push|merge|ship|pr|pull request)\b/.test(text);
+  }
+  if (action.kind === 'protected') {
+    const fname = action.target.split('/').pop().toLowerCase();
+    return text.includes(fname.toLowerCase()) || text.includes(action.target.toLowerCase());
+  }
+  return false;
+}
+
+/**
+ * Verify a transcript against the rule set. Returns a structured audit
+ * result. Side-effect free; the runtime entry point below writes the result
+ * to .cx/audit.jsonl.
+ */
+export function verifyTranscript(entries, { windowSize = 20 } = {}) {
+  const findings = [];
+  const actions = findConsequentialActions(entries);
+
+  for (const action of actions) {
+    const window = lastN(entries.slice(0, action.atIndex), windowSize);
+    const verdict = classifyApproval(window, action);
+    findings.push({
+      action: action.kind,
+      target: action.target,
+      verdict,
+      atIndex: action.atIndex,
+    });
+  }
+
+  const failed = findings.some((f) => f.verdict === 'REFUSED');
+  const inconclusive = findings.some((f) => f.verdict === 'INCONCLUSIVE');
+  let ok;
+  if (failed) ok = 'fail';
+  else if (inconclusive) ok = 'inconclusive';
+  else ok = 'pass';
+
+  return { ok, findings, actionCount: actions.length };
+}
+
+function writeAudit(cwd, payload) {
+  const path = join(cwd, AUDIT_REL);
+  try { mkdirSync(dirname(path), { recursive: true }); } catch { /* ignore */ }
+  try { appendFileSync(path, JSON.stringify(payload) + '\n'); }
+  catch (err) { logHookFailure({ hook: 'rule-verifier', err, phase: 'append-audit' }); }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  let input = {};
+  try { input = JSON.parse(readFileSync(0, 'utf8')); }
+  catch (err) { logHookFailure({ hook: 'rule-verifier', err, phase: 'parse-stdin' }); process.exit(0); }
+
+  const cwd = input?.cwd || process.cwd();
+  const transcriptPath = input?.transcript_path;
+  if (!transcriptPath || !existsSync(transcriptPath)) process.exit(0);
+
+  const entries = safeReadJsonLines(transcriptPath);
+  const result = verifyTranscript(entries);
+  writeAudit(cwd, { ts: new Date().toISOString(), hook: 'rule-verifier', ...result });
+
+  if (result.ok === 'fail' && process.env.CONSTRUCT_RULE_VERIFIER === 'block') process.exit(2);
+  process.exit(0);
+}

package/lib/hooks/session-optimize.mjs

@@ -237,7 +237,8 @@ function main() {
     console.log(`  • ${agent.name}: avgScore=${agent.avgScore}, invocations=${agent.invocations}`);
   });
   
-  // Run optimization for each agent (serial for now)
+  // Sequential optimization keeps prompt-tuning deterministic and avoids
+  // colliding writes to per-agent prompt files.
   let optimizedCount = 0;
   let failedCount = 0;
   

package/lib/init-unified.mjs

@@ -615,87 +615,76 @@ function discoverProjectDirs(targetPath) {
   return dirs.sort();
 }
 
-const INTAKE_DIR_PRESETS = [
-  { value: 'src', label: 'src/', reason: 'Source code — most projects put code here' },
-  { value: 'lib', label: 'lib/', reason: 'Library code' },
-  { value: 'packages', label: 'packages/', reason: 'Monorepo packages' },
-  { value: 'services', label: 'services/', reason: 'Microservices or backend services' },
-  { value: 'apps', label: 'apps/', reason: 'Monorepo apps' },
-  { value: 'docs', label: 'docs/', reason: 'Documentation source' },
-  { value: 'tests', label: 'tests/', reason: 'Test files' },
-  { value: 'spec', label: 'spec/', reason: 'Specifications' },
-  { value: 'infra', label: 'infra/', reason: 'Infrastructure code (Terraform, etc.)' },
-  { value: 'config', label: 'config/', reason: 'Configuration files' },
-  { value: 'scripts', label: 'scripts/', reason: 'Build/ops scripts' },
-  { value: 'tools', label: 'tools/', reason: 'Internal tooling' },
-];
+// Extra inbox-style directories the user can opt into. These are NOT
+// source-code, doc, or test directories: they're places where unsorted
+// signals tend to land (downloads, scratch notes, exported research). The
+// built-in `.cx/inbox/` and `docs/intake/` are always watched and not
+// listed here.
+//
+// Historically this list included `src/`, `docs/`, `tests/`, etc., and
+// `init --yes` auto-enabled every one that existed in the project. That
+// turned every code change, doc edit, and test file into a synthetic
+// "intake signal" and polluted the queue with hundreds of false positives.
+// Watching project artifact directories is opt-in only; an empty list is
+// the correct default.
+const INTAKE_DIR_PRESETS = [];
 
 async function askIntakeCollection(targetPath, skipInteractive) {
+  // Non-interactive default: empty parentDirs. The built-in zones
+  // (.cx/inbox/ and docs/intake/ when present) handle every well-defined
+  // signal path. Users who want to watch additional directories opt in
+  // explicitly via `construct intake config set --add-dir=<path>`.
   if (skipInteractive) {
-    // Non-interactive: auto-detect and suggest based on what exists
-    const existingDirs = discoverProjectDirs(targetPath);
-    const selected = INTAKE_DIR_PRESETS
-      .filter(preset => existingDirs.includes(preset.value))
-      .map(p => p.value);
-    
-    if (selected.length === 0) return null;
-    
-    console.log('');
-    console.log('═══════════════════════════════════════════════════════════');
-    console.log('  INTAKE COLLECTION');
-    console.log('═══════════════════════════════════════════════════════════');
-    console.log('');
-    console.log(`Auto-detected ${selected.length} directory(ies) to watch for context:`);
-    for (const d of selected) console.log(`  • ${d}/`);
-    console.log('');
-    console.log('The inbox watcher will scan these directories for new files');
-    console.log('and route them through R&D triage automatically.');
-    console.log('');
-    
-    return { parentDirs: selected, maxDepth: 4 };
+    return null;
   }
-  
-  // Interactive mode
+
+  // Interactive mode: no presets to surface — the user must name the
+  // directory they want watched. Skipped entirely when the preset list
+  // is empty (the current default after the auto-include regression).
+  if (INTAKE_DIR_PRESETS.length === 0) {
+    return null;
+  }
+
   const existingDirs = discoverProjectDirs(targetPath);
   const presetOptions = INTAKE_DIR_PRESETS.map(p => ({
     label: p.label,
     value: p.value,
-    checked: existingDirs.includes(p.value),
+    checked: false,
     description: p.reason,
   }));
-  
+
   console.log('');
   console.log('═══════════════════════════════════════════════════════════');
   console.log('  INTAKE COLLECTION');
   console.log('═══════════════════════════════════════════════════════════');
   console.log('');
-  console.log('Intake watches directories for new files and routes them');
-  console.log('through R&D triage. Select which directories to watch.');
-  console.log('(directories already found in your project are pre-checked)');
+  console.log('Intake watches `.cx/inbox/` and `docs/intake/` by default.');
+  console.log('Add extra directories ONLY if signals (customer notes, exports,');
+  console.log('PDFs, etc.) regularly land there. Do not select code or finished');
+  console.log('artifact directories like src/, docs/, or tests/.');
   console.log('');
-  
+
+  void existingDirs;
   const selected = await multiSelect({
-    title: 'Directories to Watch',
-    instructions: 'Press Enter to confirm your selection',
+    title: 'Additional Inbox Directories',
+    instructions: 'Press Enter to confirm your selection (or pick none)',
     options: presetOptions,
   });
-  
+
   if (selected.length === 0) {
     console.log('');
-    console.log('No directories selected. The inbox watcher will only scan');
-    console.log('.cx/inbox/ and docs/intake/ (built-in zones).');
-    console.log('');
-    console.log('You can always add more later with:');
-    console.log('  construct intake config set --add-dir=src');
+    console.log('No extra directories selected. The inbox watcher will scan');
+    console.log('.cx/inbox/ and docs/intake/ only. Add more later with:');
+    console.log('  construct intake config set --add-dir=<path>');
     console.log('');
     return null;
   }
-  
+
   console.log('');
-  console.log(`Watching ${selected.length} directory(ies):`);
+  console.log(`Watching ${selected.length} extra directory(ies):`);
   for (const d of selected) console.log(`  • ${d}/`);
   console.log('');
-  
+
   return { parentDirs: selected, maxDepth: 4 };
 }
 
@@ -949,18 +938,19 @@ async function main() {
     console.log('');
   }
   
-  // Intake collection — ask which directories to watch for context
+  // Intake collection — always write intake-config.json with safe defaults
+  // so the user can inspect what's watched and edit the file directly. Empty
+  // parentDirs is the correct default: the inbox watcher always scans
+  // .cx/inbox/ and docs/intake/ (when present); extra dirs are opt-in.
   console.log('[TRACE init:intake-ask]');
-  
-  const intakeConfig = await askIntakeCollection(target, skipInteractive);
-  if (intakeConfig) {
-    const { saveIntakeConfig } = await import('./intake/intake-config.mjs');
-    try {
-      saveIntakeConfig(target, intakeConfig);
-      created.push('.cx/intake-config.json');
-    } catch (err) {
-      console.warn(`⚠️  Could not write intake config: ${err.message}`);
-    }
+
+  const intakeConfig = (await askIntakeCollection(target, skipInteractive)) ?? { parentDirs: [], maxDepth: 4 };
+  const { saveIntakeConfig } = await import('./intake/intake-config.mjs');
+  try {
+    saveIntakeConfig(target, intakeConfig);
+    created.push('.cx/intake-config.json');
+  } catch (err) {
+    console.warn(`⚠️  Could not write intake config: ${err.message}`);
   }
   
   // Ask about documentation system

package/lib/intake/classify.mjs

@@ -6,6 +6,13 @@
  * rdStage, primaryOwner, recommendedChain, recommendedAction, risk,
  * requiresApproval, confidence, rationale.
  *
+ * Classification MUST be a pure function of (sourcePath, extractedText,
+ * related, profile). Same input must yield identical output across runs.
+ * Outcomes-aware re-ranking is deliberately not consulted here: cached
+ * success-rate history would make the same file classify differently
+ * across runs, which is a non-determinism bug. Outcomes can influence
+ * downstream routing, but never classify.
+ *
  * NO LLM call. The daemon path must remain synchronous and cheap; intent
  * verification belongs in offline measurement, not inline classification.
  *
@@ -39,22 +46,13 @@ export const RECOMMENDED_ACTIONS = [
   'archive',
 ];
 
-// Static profile → table map. New curated profiles register themselves here.
+// Static profile to table map. New curated profiles register themselves here.
 // Custom profiles (escape hatch) declare classificationTable as a repo-relative
 // path; that path is loaded dynamically in classifyRdIntake when a profile arg
 // supplies it.
 import operationsTable from './tables/operations.mjs';
 import creativeTable from './tables/creative.mjs';
 import researchTable from './tables/research.mjs';
-import { outcomeBoost } from '../outcomes/aggregate.mjs';
-
-// Outcome boost is a soft re-rank applied when a cwd is supplied. Capped at
-// ±0.05 in outcomeBoost itself, so the primary keyword signal (integer hits)
-// always dominates. Returns 0 if no outcome data exists for the role.
-function outcomeBoostFor(cwd, role) {
-  if (!cwd || !role) return 0;
-  try { return outcomeBoost(cwd, role); } catch { return 0; }
-}
 
 const TABLES = {
   rnd: rndTable,
@@ -63,6 +61,39 @@ const TABLES = {
   research: researchTable,
 };
 
+// Filename patterns are explicit intent signals. A match adds FILENAME_BOOST
+// to the named intakeType, which is enough to outweigh one or two stray body
+// keywords from a different type but not a clear keyword majority.
+const FILENAME_BOOST = 0.4;
+const FILENAME_HINTS = [
+  { re: /postmortem/i, intakeType: 'incident' },
+  { re: /incident-report|incident_report/i, intakeType: 'incident' },
+  { re: /^adr[-_]/i, intakeType: 'architecture' },
+  { re: /\badr[-_]\d/i, intakeType: 'architecture' },
+  { re: /^rfc[-_]/i, intakeType: 'architecture' },
+  { re: /^prd[-_]/i, intakeType: 'requirement' },
+  { re: /security|cve|vulnerability/i, intakeType: 'security' },
+  { re: /research|study|literature/i, intakeType: 'research' },
+  { re: /eval|metric|benchmark/i, intakeType: 'eval-finding' },
+  { re: /-bug\b|\bbug-/i, intakeType: 'bug' },
+  { re: /runbook/i, intakeType: 'ops' },
+];
+
+// Title-level negative keywords flip a classification away from a misleading
+// body match. A postmortem describes a bug in retrospect but is not a bug
+// report; an incident-report uses crash vocabulary but is an incident.
+// Penalty is applied only when the override matches the doc's title or first
+// H1, never on stray body mentions.
+const TITLE_PENALTY = 0.5;
+const TITLE_OVERRIDES = [
+  { re: /^#\s*postmortem\b/im, penalize: 'bug' },
+  { re: /^#\s*incident\s+report\b/im, penalize: 'bug' },
+  { re: /^#\s*post-mortem\b/im, penalize: 'bug' },
+  { re: /^#\s*architecture\s+decision\b/im, penalize: 'bug' },
+  { re: /^#\s*adr[-:\s]/im, penalize: 'bug' },
+  { re: /^#\s*security\s+(advisory|finding)\b/im, penalize: 'bug' },
+];
+
 function resolveTable(profile) {
   if (!profile) return rndTable;
   const id = typeof profile === 'string' ? profile : profile.id;
@@ -93,34 +124,65 @@ function buildSignalText({ sourcePath, extractedText, related }) {
   return normalize(`${slug} ${body} ${relatedTitles}`);
 }
 
+// Look for a filename-pattern hint. The basename, not the full path, is
+// scanned so directory names cannot accidentally bias the classification.
+function filenameHintFor(sourcePath) {
+  if (!sourcePath) return null;
+  const base = path.basename(sourcePath);
+  for (const hint of FILENAME_HINTS) {
+    if (hint.re.test(base)) return hint.intakeType;
+  }
+  return null;
+}
+
+// Detect title-level overrides on the raw extracted text (case-insensitive,
+// multiline anchored to ^# so only true H1s match).
+function titlePenaltiesFor(extractedText) {
+  const penalties = {};
+  const text = String(extractedText || '');
+  for (const rule of TITLE_OVERRIDES) {
+    if (rule.re.test(text)) {
+      penalties[rule.penalize] = (penalties[rule.penalize] || 0) + TITLE_PENALTY;
+    }
+  }
+  return penalties;
+}
+
 /**
  * Classify an intake signal against the active profile (defaults to RND).
  *
  * Backward-compatible: callers that did not pass a `profile` arg keep getting
- * RND output, byte-identical to the pre-B2 behavior.
+ * RND output for the same input. Output is deterministic. The optional `cwd`
+ * argument is accepted for backward compatibility with prior callers but is
+ * not consulted; outcomes-aware re-ranking is intentionally absent from the
+ * classify path to preserve determinism.
  *
  * @param {object} input
  * @param {string} [input.sourcePath]
  * @param {string} [input.extractedText]
  * @param {Array} [input.related]
  * @param {string|object} [input.profile] - profile id (string) or full profile object
+ * @param {string} [input.cwd] - accepted for backward compatibility, ignored
  */
-export function classifyRdIntake({ sourcePath = '', extractedText = '', related = [], profile = null, cwd = null } = {}) {
+export function classifyRdIntake({ sourcePath = '', extractedText = '', related = [], profile = null } = {}) {
   const table = resolveTable(profile);
   const signal = buildSignalText({ sourcePath, extractedText, related });
+  const filenameHint = filenameHintFor(sourcePath);
+  const titlePenalties = titlePenaltiesFor(extractedText);
 
-  let best = null;
+  // Score every entry whose keywords contribute either a body hit or a
+  // filename hint. An entry with no signal at all is skipped.
+  const scored = [];
   for (const entry of table.CLASSIFICATION_TABLE) {
     const { hits, matched } = countMatches(signal, entry.keywords);
-    if (hits === 0) continue;
-    const boost = cwd ? outcomeBoostFor(cwd, entry.primaryOwner) : 0;
-    const score = hits + boost;
-    if (!best || score > best.score) {
-      best = { entry, hits, matched, score };
-    }
+    const filenameBoost = filenameHint === entry.intakeType ? FILENAME_BOOST : 0;
+    const penalty = titlePenalties[entry.intakeType] || 0;
+    const score = hits + filenameBoost - penalty;
+    if (hits === 0 && filenameBoost === 0) continue;
+    scored.push({ entry, hits, matched, score, filenameBoost, penalty });
   }
 
-  if (!best) {
+  if (scored.length === 0) {
     return {
       ...table.UNKNOWN_TRIAGE,
       confidence: 0.3,
@@ -128,11 +190,33 @@ export function classifyRdIntake({ sourcePath = '', extractedText = '', related
     };
   }
 
-  const { entry, hits, matched } = best;
-  const confidence = Math.min(1, 0.4 + 0.2 * hits);
-  const matchedList = matched.slice(0, 4).join(', ');
-  const rationale = `Matched ${hits} keyword${hits === 1 ? '' : 's'} for ${entry.intakeType}: ${matchedList}.`;
+  // Deterministic ranking: highest score wins; ties broken by table order
+  // (stable sort preserves CLASSIFICATION_TABLE order, which is curated).
+  scored.sort((a, b) => b.score - a.score);
+  const best = scored[0];
+  const runnerUp = scored[1] || null;
+
+  // Confidence calibration: if the runner-up is within 0.1 of the winner,
+  // the signal is ambiguous and confidence is capped at 0.5. Otherwise a
+  // bounded ramp on raw hits: floor 0.4, +0.2 per hit, clamped at 1.0.
+  const margin = runnerUp ? best.score - runnerUp.score : Infinity;
+  const ambiguous = margin < 0.1;
+  const baseConfidence = Math.min(1, 0.4 + 0.2 * best.hits);
+  const confidence = ambiguous ? Math.min(0.5, baseConfidence) : baseConfidence;
+
+  const matchedList = best.matched.slice(0, 4).join(', ');
+  const rationaleParts = [];
+  if (best.hits > 0) {
+    rationaleParts.push(`matched ${best.hits} keyword${best.hits === 1 ? '' : 's'} (${matchedList || 'filename'})`);
+  }
+  if (best.filenameBoost > 0) rationaleParts.push('filename hint');
+  if (best.penalty > 0) rationaleParts.push('title override applied');
+  if (ambiguous && runnerUp) {
+    rationaleParts.push(`ambiguous vs ${runnerUp.entry.intakeType} (margin ${margin.toFixed(2)})`);
+  }
+  const rationale = `Classified as ${best.entry.intakeType}: ${rationaleParts.join('; ')}.`;
 
+  const { entry } = best;
   return {
     intakeType: entry.intakeType,
     rdStage: entry.rdStage,