@geraldmaron/construct 1.0.5 → 1.0.7

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,

package/lib/intake/daemon.mjs

@@ -0,0 +1,121 @@
+/**
+ * lib/intake/daemon.mjs — Continuous intake daemon with safeguards.
+ *
+ * Polls `.cx/inbox/` for new files, classifies them via the existing intake
+ * classifier, and writes packets to `.cx/intake/pending/`. Packets past their
+ * TTL move to `.cx/intake/dead-letter/`; failed classification retries up to
+ * the budget then dead-letters with the failure reason.
+ *
+ * Built on lib/daemons/contract.mjs — every safeguard (bounded lifetime,
+ * idle shutdown, heartbeat, killswitch, single-writer lock) applies.
+ */
+
+import { readdirSync, statSync, readFileSync, writeFileSync, renameSync, existsSync, mkdirSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { homedir } from 'node:os';
+
+import { createDaemon, classifyPacket } from '../daemons/contract.mjs';
+
+const KILLSWITCH_ENV = 'CONSTRUCT_INTAKE_DAEMON';
+
+function inboxDir(cwd) { return join(cwd, '.cx', 'inbox'); }
+function pendingDir(cwd) { return join(cwd, '.cx', 'intake', 'pending'); }
+function deadLetterDir(cwd) { return join(cwd, '.cx', 'intake', 'dead-letter'); }
+function heartbeatPath() { return join(homedir(), '.construct', 'intake-daemon.heartbeat'); }
+
+function ensureDir(dir) {
+  try { mkdirSync(dir, { recursive: true }); } catch { /* ignore */ }
+}
+
+function listInboxFiles(cwd) {
+  const dir = inboxDir(cwd);
+  if (!existsSync(dir)) return [];
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return []; }
+  return entries
+    .filter((e) => e.isFile() && !e.name.startsWith('.'))
+    .map((e) => join(dir, e.name));
+}
+
+/**
+ * Process one inbox file: classify, persist packet to pending, remove the
+ * inbox source on success, or move to dead-letter on persistent failure.
+ *
+ * Returns one of:
+ *   { didWork: true,  route: 'pending'|'dead-letter', packetId }
+ *   { didWork: false, reason }
+ */
+export async function processInboxFile(filePath, { cwd, classify, now = () => new Date() }) {
+  ensureDir(pendingDir(cwd));
+  ensureDir(deadLetterDir(cwd));
+
+  let body;
+  try { body = readFileSync(filePath, 'utf8'); }
+  catch (err) { return { didWork: false, reason: `read failed: ${err.message}` }; }
+
+  const id = `intake-${now().getTime()}-${Math.random().toString(36).slice(2, 8)}`;
+  const packet = {
+    id,
+    firstSeenAt: new Date(statSync(filePath).mtimeMs).toISOString(),
+    sourcePath: filePath,
+    excerpt: body.slice(0, 500),
+    attempts: 0,
+  };
+
+  const decision = classifyPacket(packet);
+  if (decision.route === 'dead-letter') {
+    return persistDeadLetter(filePath, packet, decision.reason, cwd);
+  }
+
+  try {
+    packet.triage = await classify({ sourcePath: filePath, extractedText: body });
+  } catch (err) {
+    packet.attempts++;
+    packet.lastError = err.message;
+    if (packet.attempts >= 3) {
+      return persistDeadLetter(filePath, packet, 'retry-budget-exhausted', cwd);
+    }
+    return { didWork: false, reason: `classify failed, will retry: ${err.message}` };
+  }
+
+  const packetPath = join(pendingDir(cwd), `${id}.json`);
+  writeFileSync(packetPath, JSON.stringify(packet, null, 2));
+  try {
+    const consumedPath = join(pendingDir(cwd), `.${basename(filePath)}.consumed`);
+    renameSync(filePath, consumedPath);
+  } catch { /* ignore consume failure */ }
+  return { didWork: true, route: 'pending', packetId: id };
+}
+
+function persistDeadLetter(filePath, packet, reason, cwd) {
+  const dlPath = join(deadLetterDir(cwd), `${packet.id}.json`);
+  writeFileSync(dlPath, JSON.stringify({ ...packet, deadLetterReason: reason, deadLetteredAt: new Date().toISOString() }, null, 2));
+  try { renameSync(filePath, join(deadLetterDir(cwd), `.source.${basename(filePath)}`)); } catch { /* ignore */ }
+  return { didWork: true, route: 'dead-letter', packetId: packet.id, reason };
+}
+
+/**
+ * Build a DaemonRunner for the intake daemon. Caller is responsible for
+ * calling .run() — typically construct intake daemon start.
+ */
+export function buildIntakeDaemon({ cwd = process.cwd(), intervalMs = 60_000, classify } = {}) {
+  const classifyFn = classify || (async () => ({ intakeType: 'unknown', rdStage: 'triage', primaryOwner: 'product-manager', recommendedAction: 'review' }));
+  return createDaemon({
+    name: 'intake',
+    intervalMs,
+    killswitchEnv: KILLSWITCH_ENV,
+    heartbeatPath: heartbeatPath(),
+    maxRuntimeMs: 24 * 60 * 60 * 1000,
+    maxIdleTicks: 6,
+    async tick() {
+      const files = listInboxFiles(cwd);
+      if (files.length === 0) return { didWork: false };
+      let workedAny = false;
+      for (const file of files) {
+        const result = await processInboxFile(file, { cwd, classify: classifyFn });
+        if (result.didWork) workedAny = true;
+      }
+      return { didWork: workedAny };
+    },
+  });
+}

package/lib/intake/filesystem-queue.mjs

@@ -10,6 +10,7 @@
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+import { ensureCxDir } from '../project-init-shared.mjs';
 
 const QUEUE_SUBDIR = '.cx/intake';
 
@@ -55,6 +56,7 @@ export class FilesystemIntakeQueue {
   enqueue(entry) {
     if (!entry?.intake?.sourcePath) throw new Error('enqueue: entry.intake.sourcePath is required');
     const dir = pendingDir(this.rootDir);
+    ensureCxDir(this.rootDir);
     mkdirSync(dir, { recursive: true });
 
     const ts = timestamp();
@@ -112,6 +114,7 @@ export class FilesystemIntakeQueue {
     if (notes) data.notes = notes;
 
     const dst = path.join(processedDir(this.rootDir), `${id}.json`);
+    ensureCxDir(this.rootDir);
     mkdirSync(path.dirname(dst), { recursive: true });
     writeFileSync(dst, JSON.stringify(data, null, 2) + '\n', 'utf8');
     rmSync(src);
@@ -128,6 +131,7 @@ export class FilesystemIntakeQueue {
     if (reason) data.reason = reason;
 
     const dst = path.join(skippedDir(this.rootDir), `${id}.json`);
+    ensureCxDir(this.rootDir);
     mkdirSync(path.dirname(dst), { recursive: true });
     writeFileSync(dst, JSON.stringify(data, null, 2) + '\n', 'utf8');
     rmSync(src);
@@ -148,7 +152,8 @@ export class FilesystemIntakeQueue {
       delete data.reason;
 
       const dst = path.join(pendingDir(this.rootDir), `${id}.json`);
-      mkdirSync(path.dirname(dst), { recursive: true });
+      ensureCxDir(this.rootDir);
+    mkdirSync(path.dirname(dst), { recursive: true });
       writeFileSync(dst, JSON.stringify(data, null, 2) + '\n', 'utf8');
       rmSync(src);
       return { id, filePath: dst, from: path.basename(dir) };

package/lib/intake/intake-config.mjs

@@ -24,6 +24,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
 import { shouldCreateCx } from '../project-detection.mjs';
+import { ensureCxDir } from '../project-init-shared.mjs';
 
 export const INTAKE_CONFIG_FILE = '.cx/intake-config.json';
 export const INTAKE_DEFAULT_MAX_DEPTH = 4;
@@ -115,7 +116,7 @@ export function saveIntakeConfig(rootDir, patch = {}) {
   };
 
   const file = intakeConfigPath(rootDir);
-  mkdirSync(join(rootDir, '.cx'), { recursive: true });
+  ensureCxDir(rootDir);
   writeFileSync(file, JSON.stringify(next, null, 2) + '\n');
   return next;
 }

package/lib/intake/prepare.mjs

@@ -77,7 +77,6 @@ export async function prepareIntakeForIngestedFile({
     extractedText: extracted,
     related,
     profile: activeProfile?.id,
-    cwd: rootDir,
   });
 
   // Detect customer mentions and update profiles

package/lib/intake/session-prelude.mjs

@@ -13,6 +13,7 @@
 import { createIntakeQueue } from './queue.mjs';
 import { formatTriageLine } from './classify.mjs';
 import { isBrokered } from '../mcp/broker.mjs';
+import { getRebrand } from '../profiles/rebrand.mjs';
 
 export function buildIntakePrelude({ cwd, env = process.env } = {}) {
   if (!cwd) return '';
@@ -20,11 +21,16 @@ export function buildIntakePrelude({ cwd, env = process.env } = {}) {
     const queue = createIntakeQueue(cwd, env);
     const pending = queue.listPending();
     if (!pending.length) return '';
+    const { intakeQueueLabel, signalNoun } = getRebrand(cwd);
     const recent = pending.slice(-3).map((p) => {
       const src = p.intake?.sourcePath || p.id;
       return `- ${formatTriageLine(src, p.triage)}`;
     });
-    return `\n## Pending R&D intake (${pending.length})\n${recent.join('\n')}\nEach packet at \`.cx/intake/pending/<id>.json\` carries the new signal, a triage block (intakeType, rdStage, primaryOwner, recommendedChain, recommendedAction, risk), related existing docs, and an excerpt. Process via the recommended chain, then close via \`construct intake done <id>\`.\n`;
+    // Strip a trailing " queue" / " intake" so the heading reads
+    // "## Pending R&D intake (N)" rather than the redundant
+    // "## Pending R&D intake queue queue (N)".
+    const heading = intakeQueueLabel.replace(/\s+queue$/i, '');
+    return `\n## Pending ${heading} (${pending.length})\n${recent.join('\n')}\nEach packet at \`.cx/intake/pending/<id>.json\` carries the new ${signalNoun}, a triage block (intakeType, rdStage, primaryOwner, recommendedChain, recommendedAction, risk), related existing docs, and an excerpt. Process via the recommended chain, then close via \`construct intake done <id>\`.\n`;
   } catch {
     return '';
   }

package/lib/intake/traceability.mjs

@@ -0,0 +1,90 @@
+/**
+ * lib/intake/traceability.mjs — stamps intake provenance into artifact frontmatter.
+ *
+ * Backs `construct intake done <id> --output=<path>`: reads the intake packet,
+ * extracts (id, confidence, rationale), and writes them into the artifact's
+ * YAML frontmatter. Refuses to overwrite a different intake_id (an artifact
+ * can be linked to exactly one intake source). Idempotent on re-stamping.
+ *
+ * Read by docs:verify checkIntakeTraceability to surface artifacts in
+ * intake-fed locations that lack a reference.
+ *
+ * Field schema (in artifact YAML frontmatter):
+ *   intake_id: construct-xxx
+ *   intake_confidence: 0.7
+ *   intake_rationale: "Matched 3 keywords: dashboard, latency, p95"
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+
+export function parseArtifactFrontmatter(content) {
+  const m = content.match(FRONTMATTER_RE);
+  if (!m) return { frontmatter: {}, body: content, hasBlock: false };
+  const out = {};
+  for (const line of m[1].split('\n')) {
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    const rawValue = line.slice(idx + 1).trim();
+    if (!key) continue;
+    const unquoted = rawValue.replace(/^["']|["']$/g, '');
+    if (/^-?\d+(\.\d+)?$/.test(unquoted)) out[key] = Number(unquoted);
+    else out[key] = unquoted;
+  }
+  return { frontmatter: out, body: content.slice(m[0].length), hasBlock: true };
+}
+
+function serializeFrontmatter(fm) {
+  const lines = ['---'];
+  for (const [k, v] of Object.entries(fm)) {
+    if (v === null || v === undefined) continue;
+    if (typeof v === 'number' || typeof v === 'boolean') {
+      lines.push(`${k}: ${v}`);
+    } else {
+      const s = String(v);
+      const needsQuoting = /[:#"'\n]|^\s|\s$/.test(s);
+      lines.push(`${k}: ${needsQuoting ? JSON.stringify(s) : s}`);
+    }
+  }
+  lines.push('---');
+  return lines.join('\n');
+}
+
+export function stampIntakeProvenance(artifactPath, { intakeId, confidence, rationale }) {
+  if (!existsSync(artifactPath)) {
+    throw new Error(`Output artifact not found: ${artifactPath}`);
+  }
+  if (!intakeId) throw new Error('intakeId required for stamping');
+  const content = readFileSync(artifactPath, 'utf8');
+  const { frontmatter, body, hasBlock } = parseArtifactFrontmatter(content);
+
+  const existing = frontmatter.intake_id;
+  if (existing && existing !== intakeId) {
+    throw new Error(
+      `Refusing to overwrite intake_id: artifact already references ${existing}, not ${intakeId}. Resolve manually or supersede.`,
+    );
+  }
+
+  const next = {
+    ...frontmatter,
+    intake_id: intakeId,
+    ...(confidence !== undefined && confidence !== null ? { intake_confidence: confidence } : {}),
+    ...(rationale ? { intake_rationale: rationale } : {}),
+  };
+
+  const fmText = serializeFrontmatter(next);
+  const out = hasBlock ? `${fmText}\n${body}` : `${fmText}\n\n${content}`;
+  writeFileSync(artifactPath, out, 'utf8');
+  return { intake_id: intakeId, intake_confidence: next.intake_confidence, intake_rationale: next.intake_rationale };
+}
+
+export function hasIntakeReference(artifactPath) {
+  if (!existsSync(artifactPath)) return false;
+  const { frontmatter } = parseArtifactFrontmatter(readFileSync(artifactPath, 'utf8'));
+  if (frontmatter.intake_id) return true;
+  if (frontmatter.intake === 'none') return true;
+  return false;
+}