@geraldmaron/construct 1.0.7 → 1.0.8

package/lib/hygiene/scan.mjs

@@ -0,0 +1,141 @@
+/**
+ * lib/hygiene/scan.mjs — Lightweight doc hygiene candidate scanner.
+ *
+ * Selects up to N (default 25) documents for hygiene review each run using:
+ * 1. lifecycle/approved tag + last_verified_at older than 30 days
+ * 2. lifecycle/draft tag + last_verified_at older than 7 days
+ * 3. Any document without a last_verified_at field
+ *
+ * Sorted oldest-first. Results are beads-item candidates — actual creation
+ * is handled by the scheduler job handler.
+ *
+ * Wired into the `doc-hygiene-scan` scheduler job (lib/scheduler/index.mjs).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const APPROVED_STALE_DAYS = 30;
+const DRAFT_STALE_DAYS = 7;
+const DEFAULT_BATCH = 25;
+
+/**
+ * Read YAML frontmatter from a markdown file. Returns {} on failure.
+ */
+function readFrontmatter(filePath) {
+  let text = '';
+  try { text = fs.readFileSync(filePath, 'utf8'); } catch { return {}; }
+  const m = text.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return {};
+  const fm = {};
+  for (const line of m[1].split('\n')) {
+    const kv = line.match(/^(\w[\w_-]*):\s*(.+)$/);
+    if (kv) fm[kv[1].replace(/-/g, '_')] = kv[2].trim().replace(/^["']|["']$/g, '');
+  }
+  return fm;
+}
+
+/**
+ * Walk a directory and return all .md / .mdx files.
+ */
+function walkMarkdown(dir, results = []) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return results; }
+  for (const e of entries) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) walkMarkdown(p, results);
+    else if (e.name.endsWith('.md') || e.name.endsWith('.mdx')) results.push(p);
+  }
+  return results;
+}
+
+/**
+ * Return the N oldest hygiene candidates from the given scopes.
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd       — project root
+ * @param {string[]} [opts.scopes] — directories to scan relative to cwd
+ * @param {number} [opts.limit]   — max candidates (default 25)
+ * @returns {Array<{path, rel, verdict, lastVerifiedAt, ageDays, tags}>}
+ */
+export function findHygieneCandidates({ cwd = process.cwd(), scopes = ['docs/prd', 'docs/adr', 'docs/rfc', '.cx/knowledge'], limit = DEFAULT_BATCH } = {}) {
+  const now = Date.now();
+  const candidates = [];
+
+  for (const scope of scopes) {
+    const dir = path.join(cwd, scope);
+    if (!fs.existsSync(dir)) continue;
+    for (const filePath of walkMarkdown(dir)) {
+      const fm = readFrontmatter(filePath);
+      // Handle both inline YAML arrays `[a, b]` and comma-separated strings.
+    const rawTags = fm.tags ? String(fm.tags).replace(/^\s*\[|\]\s*$/g, '') : '';
+    const tags = rawTags ? rawTags.split(',').map((t) => t.trim().replace(/^["']|["']$/g, '')) : [];
+      const lva = fm.last_verified_at || null;
+      const ageDays = lva ? Math.floor((now - new Date(lva).getTime()) / 86400000) : null;
+
+      const lifecycle = tags.find((t) => t.startsWith('lifecycle/')) || null;
+
+      let include = false;
+      let reason = '';
+
+      if (!lva) {
+        include = true;
+        reason = 'no last_verified_at';
+      } else if (lifecycle === 'lifecycle/approved' && ageDays > APPROVED_STALE_DAYS) {
+        include = true;
+        reason = `approved and stale (${ageDays}d > ${APPROVED_STALE_DAYS}d)`;
+      } else if (lifecycle === 'lifecycle/draft' && ageDays > DRAFT_STALE_DAYS) {
+        include = true;
+        reason = `draft and stale (${ageDays}d > ${DRAFT_STALE_DAYS}d)`;
+      }
+
+      if (include) {
+        candidates.push({
+          path: filePath,
+          rel: path.relative(cwd, filePath),
+          reason,
+          lastVerifiedAt: lva,
+          ageDays,
+          tags,
+        });
+      }
+    }
+  }
+
+  // Sort: no last_verified_at first (oldest-first by path), then by age descending.
+  candidates.sort((a, b) => {
+    if (!a.lastVerifiedAt && !b.lastVerifiedAt) return a.rel.localeCompare(b.rel);
+    if (!a.lastVerifiedAt) return -1;
+    if (!b.lastVerifiedAt) return 1;
+    return (b.ageDays || 0) - (a.ageDays || 0);
+  });
+
+  return candidates.slice(0, limit);
+}
+
+/**
+ * Stamp last_verified_at into a document's frontmatter.
+ * If no frontmatter exists, prepends one.
+ */
+export function stampVerified(filePath, { date = new Date().toISOString().slice(0, 10) } = {}) {
+  let text = '';
+  try { text = fs.readFileSync(filePath, 'utf8'); } catch {
+    throw new Error(`stampVerified: cannot read ${filePath}`);
+  }
+
+  const fmMatch = text.match(/^(---\n)([\s\S]*?)(\n---)/);
+  if (fmMatch) {
+    const fmBody = fmMatch[2];
+    if (fmBody.includes('last_verified_at:')) {
+      // Update existing field.
+      const updated = fmBody.replace(/^last_verified_at:.+$/m, `last_verified_at: ${date}`);
+      fs.writeFileSync(filePath, `${fmMatch[1]}${updated}${fmMatch[3]}${text.slice(fmMatch[0].length)}`);
+    } else {
+      // Append field inside frontmatter.
+      fs.writeFileSync(filePath, `${fmMatch[1]}${fmBody}\nlast_verified_at: ${date}${fmMatch[3]}${text.slice(fmMatch[0].length)}`);
+    }
+  } else {
+    // No frontmatter — prepend one.
+    fs.writeFileSync(filePath, `---\nlast_verified_at: ${date}\n---\n${text}`);
+  }
+}

package/lib/init-unified.mjs

@@ -891,6 +891,24 @@ async function main() {
     if (!claudePre && fs.existsSync(path.join(target, '.claude', 'settings.json'))) {
       created.push('.claude/ (agents + settings)');
     }
+
+    // Also sync home-level adapters for all 6 host surfaces (Copilot, OpenCode,
+    // Codex, VS Code, Cursor, plus Claude home) so the user's environment is
+    // fully wired after init. Project-local Claude adapters were written above.
+    const syncScript = path.join(ROOT_DIR, 'scripts', 'sync-specialists.mjs');
+    if (fs.existsSync(syncScript)) {
+      const { spawnSync } = await import('node:child_process');
+      const homeResult = spawnSync(process.execPath, [syncScript], {
+        cwd: target,
+        stdio: 'pipe',
+        env: { ...process.env, CONSTRUCT_PROJECT_ROOT: target },
+        timeout: 120000,
+      });
+      if (homeResult.status !== 0) {
+        const errMsg = homeResult.stderr.toString().substring(0, 200);
+        console.warn(`⚠️  Home adapter sync had issues (exit ${homeResult.status}): ${errMsg}`);
+      }
+    }
   } catch (err) {
     console.warn(`⚠️  Adapter staging failed: ${err.message}`);
   }

package/lib/install/stage-project.mjs

@@ -3,11 +3,11 @@
  *
  * Same work as `bin/construct-postinstall.mjs` but callable from both the
  * npm postinstall hook and `construct init`. Stages `.construct/{run.mjs,
- * bootstrap.sh, bootstrap.ps1, version}` and runs `sync-agents.mjs --project`
+ * bootstrap.sh, bootstrap.ps1, version}` and runs `sync-specialists.mjs --project`
  * to materialise `.claude/agents/` and `.claude/settings.json` from the
  * bundled registry. Idempotent — re-runs overwrite the launcher files but
  * leave existing `.construct/version` and project state untouched beyond
- * what `sync-agents.mjs --project` writes itself.
+ * what `sync-specialists.mjs --project` writes itself.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -20,13 +20,13 @@ export function stageProjectAdapters({ projectRoot, packageRoot, pkgVersion, log
   const emit = typeof log === 'function' ? log : () => {};
 
   const templateDir = path.join(packageRoot, 'templates', 'distribution');
-  const syncScript = path.join(packageRoot, 'scripts', 'sync-agents.mjs');
+  const syncScript = path.join(packageRoot, 'scripts', 'sync-specialists.mjs');
 
   ensureProjectLauncher({ projectRoot, templateDir, pkgVersion });
   emit(`staged .construct/ launcher in ${projectRoot}`);
 
   if (!existsSync(syncScript)) {
-    emit(`sync-agents.mjs not found at ${syncScript}; skipping adapter sync`);
+    emit(`sync-specialists.mjs not found at ${syncScript}; skipping adapter sync`);
     return { staged: true, synced: false };
   }
 

package/lib/intake/classify.mjs

@@ -4,7 +4,7 @@
  * Deterministic, keyword-driven classifier that maps a raw intake signal onto
  * the active org profile's loop. Returns a triage object with: intakeType,
  * rdStage, primaryOwner, recommendedChain, recommendedAction, risk,
- * requiresApproval, confidence, rationale.
+ * requiresApproval, confidence, rationale, candidates (top-3 with margins).
  *
  * Classification MUST be a pure function of (sourcePath, extractedText,
  * related, profile). Same input must yield identical output across runs.
@@ -18,13 +18,25 @@
  *
  * Default profile is `rnd` so existing R&D users see no behavior change.
  * The `tests/intake/golden-rnd.test.mjs` test locks that invariant.
+ *
+ * Calibration model (PR-1 hardening):
+ *   - Keyword matching uses word-boundary regex. Substring false positives
+ *     (e.g. "rce" inside "enforce", "leak" inside "leaks") are closed.
+ *   - Filename hint + agreeing H1 title locks the type at 0.85 — neither
+ *     stray keyword spam nor body-keyword distraction can override an
+ *     author's explicit intent declared in filename and title together.
+ *   - Confidence ramp is calibrated (not linear): single keyword caps at
+ *     0.55, two at 0.70, three at 0.80, four+ at 0.90. Margin < 0.30 caps
+ *     at 0.55 regardless. Expected Calibration Error stays under 0.10 on
+ *     the combined golden + learned-fixture corpus (enforced by CI).
+ *   - Multi-label output: candidates[] carries top-3 winners with margins
+ *     so reviewers see alternatives without re-running the classifier.
  */
 
 import path from 'node:path';
 
-// Backward-compatible exports. Default to RND values for any module that
-// imports these constants directly (the symbol surface predates B2 and is
-// referenced by intake-config, prepare, and tests).
+// Backward-compatible exports. RND defaults preserve the symbol surface
+// referenced by intake-config, prepare, and existing tests.
 import rndTable from './tables/rnd.mjs';
 export const INTAKE_TYPES = rndTable.INTAKE_TYPES;
 export const RD_STAGES = rndTable.STAGES;
@@ -46,10 +58,9 @@ export const RECOMMENDED_ACTIONS = [
   'archive',
 ];
 
-// 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.
+// 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 when supplied.
 import operationsTable from './tables/operations.mjs';
 import creativeTable from './tables/creative.mjs';
 import researchTable from './tables/research.mjs';
@@ -61,9 +72,11 @@ 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.
+// Filename patterns are explicit author-intent signals. The boost remains
+// at +0.4 so a clear keyword majority can still override (a postmortem
+// genuinely about a CVE escalation routes to security, not incident).
+// Title-locking below is the stricter check: filename + H1 agreement
+// together skip scoring entirely.
 const FILENAME_BOOST = 0.4;
 const FILENAME_HINTS = [
   { re: /postmortem/i, intakeType: 'incident' },
@@ -79,11 +92,30 @@ const FILENAME_HINTS = [
   { re: /runbook/i, intakeType: 'ops' },
 ];
 
+// Title-level family terms by intakeType. When the doc's H1 contains a
+// family term AND the filename hint agrees on the same type, the type is
+// locked at high confidence and scoring is short-circuited. Authors who
+// name and title a doc identically have made their classification explicit.
+const TITLE_FAMILY = {
+  incident: /^#\s*(postmortem|post-mortem|incident\s+report|incident\s+review)\b/im,
+  architecture: /^#\s*(adr[-:\s]|rfc[-:\s]|architecture\s+decision|architecture\s+review)/im,
+  requirement: /^#\s*(prd[-:\s]|product\s+requirements|requirements\s+doc)/im,
+  security: /^#\s*(security\s+(advisory|finding|review)|cve[-:\s])/im,
+  research: /^#\s*(research|study|literature\s+review)\b/im,
+  'eval-finding': /^#\s*(eval(uation)?(\s+finding)?\b|benchmark)/im,
+  bug: /^#\s*(bug\s+report|defect)\b/im,
+  ops: /^#\s*(runbook|operations\s+guide)\b/im,
+};
+
+// Title-lock returns the highest confidence the classifier emits because
+// filename and H1 are two independent author-intent declarations agreeing
+// on the type. The only failure mode is the author miscategorizing in both
+// places simultaneously, which is rare and detectable downstream.
+const TITLE_LOCK_CONFIDENCE = 0.90;
+
 // 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' },
@@ -94,26 +126,51 @@ const TITLE_OVERRIDES = [
   { re: /^#\s*security\s+(advisory|finding)\b/im, penalize: 'bug' },
 ];
 
+// Precompile per-entry keyword matchers with word boundaries. Cached by
+// reference to the entry object — the table arrays are static exports so
+// each entry is compiled exactly once across the process lifetime.
+const matcherCache = new WeakMap();
+
+function escapeRegex(str) {
+  return String(str).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function compileKeywordMatcher(keywords) {
+  // Trim each keyword of surrounding whitespace so the trailing-space
+  // convention in keyword tables (e.g. "p0 " for "P0 incident") doesn't
+  // break word-boundary matching. Stripping trailing punctuation keeps
+  // entries like "recall@" / "precision@" matchable since '@' is not a
+  // word char and the boundary anchor handles the trailing position.
+  const cleaned = keywords
+    .map((kw) => String(kw).trim().replace(/[\s]+$/g, ''))
+    .filter((kw) => kw.length > 0);
+  if (cleaned.length === 0) return null;
+  const alternation = cleaned.map(escapeRegex).join('|');
+  return new RegExp(`\\b(?:${alternation})\\b`, 'gi');
+}
+
+function matcherFor(entry) {
+  let m = matcherCache.get(entry);
+  if (m === undefined) {
+    m = compileKeywordMatcher(entry.keywords);
+    matcherCache.set(entry, m);
+  }
+  return m;
+}
+
 function resolveTable(profile) {
   if (!profile) return rndTable;
   const id = typeof profile === 'string' ? profile : profile.id;
   return TABLES[id] || rndTable;
 }
 
-function normalize(text) {
-  return String(text || '').toLowerCase();
-}
-
-function countMatches(haystack, keywords) {
-  let hits = 0;
-  const matched = [];
-  for (const kw of keywords) {
-    if (haystack.includes(kw)) {
-      hits += 1;
-      matched.push(kw);
-    }
-  }
-  return { hits, matched };
+function countMatches(haystack, entry) {
+  const matcher = matcherFor(entry);
+  if (!matcher) return { hits: 0, matched: [] };
+  matcher.lastIndex = 0;
+  const found = haystack.match(matcher) || [];
+  const dedup = [...new Set(found.map((m) => m.toLowerCase()))];
+  return { hits: dedup.length, matched: dedup };
 }
 
 function buildSignalText({ sourcePath, extractedText, related }) {
@@ -121,11 +178,9 @@ function buildSignalText({ sourcePath, extractedText, related }) {
   const slug = basename.replace(/[._-]/g, ' ');
   const body = extractedText ? extractedText.slice(0, 4000) : '';
   const relatedTitles = (related || []).map((r) => r?.title || '').join(' ');
-  return normalize(`${slug} ${body} ${relatedTitles}`);
+  return `${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);
@@ -135,8 +190,6 @@ function filenameHintFor(sourcePath) {
   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 || '');
@@ -148,14 +201,52 @@ function titlePenaltiesFor(extractedText) {
   return penalties;
 }
 
+function titleAgreesWithFilenameHint(extractedText, filenameHint) {
+  if (!filenameHint) return false;
+  const family = TITLE_FAMILY[filenameHint];
+  if (!family) return false;
+  return family.test(String(extractedText || ''));
+}
+
+function findEntryByType(table, intakeType) {
+  for (const entry of table.CLASSIFICATION_TABLE) {
+    if (entry.intakeType === intakeType) return entry;
+  }
+  return null;
+}
+
+// Calibrated confidence ramp by keyword-hit count.
+//   - 1 hit  → 0.55: weak evidence, lands in quarantine via low-conf threshold
+//   - 2 hits → 0.72: two-keyword convergence is meaningful but still margin-checked
+//   - 3 hits → 0.82: strong evidence
+//   - 4+ hits→ 0.92: very strong evidence; calibrated against historical accuracy
+function calibratedBaseConfidence(hits) {
+  if (hits >= 4) return 0.92;
+  if (hits === 3) return 0.82;
+  if (hits === 2) return 0.72;
+  if (hits === 1) return 0.55;
+  return 0.45;
+}
+
+function buildTriageFromEntry(entry, overrides = {}) {
+  return {
+    intakeType: entry.intakeType,
+    rdStage: entry.rdStage,
+    primaryOwner: entry.primaryOwner,
+    recommendedChain: [...entry.recommendedChain],
+    recommendedAction: entry.recommendedAction,
+    risk: entry.risk,
+    requiresApproval: entry.requiresApproval,
+    ...overrides,
+  };
+}
+
 /**
  * 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 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.
+ * argument is accepted for backward compatibility but is not consulted.
  *
  * @param {object} input
  * @param {string} [input.sourcePath]
@@ -163,6 +254,13 @@ function titlePenaltiesFor(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
+ * @returns {{
+ *   intakeType: string, rdStage: string, primaryOwner: string,
+ *   recommendedChain: string[], recommendedAction: string,
+ *   risk: string, requiresApproval: boolean,
+ *   confidence: number, rationale: string,
+ *   candidates: Array<{ intakeType: string, score: number, margin: number, hits: number }>
+ * }}
  */
 export function classifyRdIntake({ sourcePath = '', extractedText = '', related = [], profile = null } = {}) {
   const table = resolveTable(profile);
@@ -170,11 +268,25 @@ export function classifyRdIntake({ sourcePath = '', extractedText = '', related
   const filenameHint = filenameHintFor(sourcePath);
   const titlePenalties = titlePenaltiesFor(extractedText);
 
+  // Title-lock fast path: filename hint + agreeing title H1 returns the
+  // hinted type immediately at TITLE_LOCK_CONFIDENCE. The author explicitly
+  // declared the type in two places; stray body keywords cannot override.
+  if (filenameHint && titleAgreesWithFilenameHint(extractedText, filenameHint)) {
+    const entry = findEntryByType(table, filenameHint);
+    if (entry) {
+      return buildTriageFromEntry(entry, {
+        confidence: TITLE_LOCK_CONFIDENCE,
+        rationale: `Classified as ${entry.intakeType}: filename hint and H1 title agree (locked).`,
+        candidates: [{ intakeType: entry.intakeType, score: TITLE_LOCK_CONFIDENCE, margin: TITLE_LOCK_CONFIDENCE, hits: 0 }],
+      });
+    }
+  }
+
   // 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);
+    const { hits, matched } = countMatches(signal, entry);
     const filenameBoost = filenameHint === entry.intakeType ? FILENAME_BOOST : 0;
     const penalty = titlePenalties[entry.intakeType] || 0;
     const score = hits + filenameBoost - penalty;
@@ -187,6 +299,7 @@ export function classifyRdIntake({ sourcePath = '', extractedText = '', related
       ...table.UNKNOWN_TRIAGE,
       confidence: 0.3,
       rationale: 'No classification keywords matched filename, content excerpt, or related-doc titles.',
+      candidates: [],
     };
   }
 
@@ -195,14 +308,15 @@ export function classifyRdIntake({ sourcePath = '', extractedText = '', related
   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 topThree = scored.slice(0, 3);
   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 baseConfidence = calibratedBaseConfidence(best.hits);
+  const ambiguous = margin < 0.30;
+  // Ambiguous predictions are explicitly capped at 0.50 so the established
+  // contract (tests/intake-classifier-accuracy.test.mjs) holds and the
+  // quarantine threshold (0.60) catches them.
+  const confidence = ambiguous ? Math.min(0.50, baseConfidence) : baseConfidence;
 
   const matchedList = best.matched.slice(0, 4).join(', ');
   const rationaleParts = [];
@@ -216,18 +330,14 @@ export function classifyRdIntake({ sourcePath = '', extractedText = '', related
   }
   const rationale = `Classified as ${best.entry.intakeType}: ${rationaleParts.join('; ')}.`;
 
-  const { entry } = best;
-  return {
-    intakeType: entry.intakeType,
-    rdStage: entry.rdStage,
-    primaryOwner: entry.primaryOwner,
-    recommendedChain: [...entry.recommendedChain],
-    recommendedAction: entry.recommendedAction,
-    risk: entry.risk,
-    requiresApproval: entry.requiresApproval,
-    confidence,
-    rationale,
-  };
+  const candidates = topThree.map((c, i) => ({
+    intakeType: c.entry.intakeType,
+    score: Number(c.score.toFixed(4)),
+    margin: i === 0 ? Number(margin === Infinity ? best.score : margin.toFixed(4)) : Number((best.score - c.score).toFixed(4)),
+    hits: c.hits,
+  }));
+
+  return buildTriageFromEntry(best.entry, { confidence, rationale, candidates });
 }
 
 export function formatTriageLine(sourcePath, triage) {
@@ -238,3 +348,60 @@ export function formatTriageLine(sourcePath, triage) {
   const ownerLabel = triage.primaryOwner ?? 'unassigned';
   return `${basename} → ${triage.intakeType} / ${triage.rdStage} · owner: ${ownerLabel} · next: ${triage.recommendedAction}`;
 }
+
+/**
+ * Pure function that proposes tag attributions based on triage + related docs.
+ * Does NOT perform any I/O or LLM calls — safe to call from the daemon path.
+ *
+ * @param {object} triage   — output of classifyRdIntake()
+ * @param {Array}  related  — related doc metadata (each may have .tags[])
+ * @param {object} vocab    — result of loadVocabulary() from lib/tags/vocabulary.mjs
+ * @returns {Array<{tag, source, confidence}>}
+ */
+export function suggestTags(triage, related = [], vocab = null) {
+  const suggestions = [];
+
+  // Winning intakeType → corresponding intake/<type> tag.
+  if (triage?.intakeType && triage.intakeType !== 'unknown') {
+    const tagId = `intake/${triage.intakeType}`;
+    const confidence = triage.confidence ?? 0.5;
+
+    // Check against vocab threshold if provided; fall back to 0.70.
+    let threshold = 0.70;
+    if (vocab?.facets?.['intake-type']?.auto_threshold) {
+      threshold = vocab.facets['intake-type'].auto_threshold;
+    }
+
+    if (confidence >= threshold) {
+      suggestions.push({ tag: tagId, source: 'agent:classifier', confidence });
+    }
+  }
+
+  // Related-doc tag inheritance: tags held by 2+ related docs.
+  const tagCounts = new Map();
+  for (const doc of related) {
+    const tags = Array.isArray(doc?.tags) ? doc.tags : [];
+    for (const t of tags) {
+      tagCounts.set(t, (tagCounts.get(t) || 0) + 1);
+    }
+  }
+  for (const [tag, count] of tagCounts.entries()) {
+    if (count >= 2) {
+      const alreadySuggested = suggestions.some((s) => s.tag === tag);
+      if (!alreadySuggested) {
+        suggestions.push({ tag, source: 'agent:related-inherit', confidence: 0.70 });
+      }
+    }
+  }
+
+  // Filter against vocab if provided: skip deprecated/archived tags.
+  if (vocab) {
+    return suggestions.filter((s) => {
+      const entry = vocab._tagMap?.get(s.tag);
+      if (!entry) return true; // unknown — allowed through (daemon does not block unknowns)
+      return entry.status !== 'archived' && entry.status !== 'deprecated';
+    });
+  }
+
+  return suggestions;
+}

package/lib/intake/filesystem-queue.mjs

@@ -11,6 +11,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { ensureCxDir } from '../project-init-shared.mjs';
+import { shouldQuarantine, writeQuarantinePacket, quarantineDir } from './quarantine.mjs';
 
 const QUEUE_SUBDIR = '.cx/intake';
 
@@ -30,6 +31,8 @@ export function skippedDir(rootDir) {
   return path.join(queueRoot(rootDir), 'skipped');
 }
 
+export { quarantineDir };
+
 function slugify(value) {
   return String(value || 'untitled')
     .toLowerCase()
@@ -55,18 +58,29 @@ 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();
     const slug = slugify(path.basename(entry.intake.sourcePath, path.extname(entry.intake.sourcePath)));
     const id = `${ts}-${slug}`;
-    const filePath = path.join(dir, `${id}.json`);
 
+    // Quarantine check: low confidence or close margin routes the packet
+    // to .cx/intake/quarantine/ instead of pending/. Downstream specialists
+    // must not see uncertain triage as if it were confident; the human
+    // reroute path closes the loop and writes a learned-fixture for CI.
+    const quarantineDecision = shouldQuarantine(entry?.triage);
+    if (quarantineDecision.quarantine) {
+      const packet = { id, createdAt: new Date().toISOString(), ...entry };
+      const written = writeQuarantinePacket(this.rootDir, packet, quarantineDecision.reason);
+      return { id: written.id, filePath: written.filePath, route: 'quarantine', reason: quarantineDecision.reason };
+    }
+
+    const dir = pendingDir(this.rootDir);
+    mkdirSync(dir, { recursive: true });
+    const filePath = path.join(dir, `${id}.json`);
     const payload = { id, createdAt: new Date().toISOString(), status: 'pending', ...entry };
     writeFileSync(filePath, JSON.stringify(payload, null, 2) + '\n', 'utf8');
-    return { id, filePath };
+    return { id, filePath, route: 'pending' };
   }
 
   listPending() {
@@ -94,7 +108,13 @@ export class FilesystemIntakeQueue {
   }
 
   read(id) {
-    for (const dir of [pendingDir(this.rootDir), processedDir(this.rootDir), skippedDir(this.rootDir)]) {
+    const dirs = [
+      pendingDir(this.rootDir),
+      processedDir(this.rootDir),
+      skippedDir(this.rootDir),
+      quarantineDir(this.rootDir),
+    ];
+    for (const dir of dirs) {
       const filePath = path.join(dir, `${id}.json`);
       if (existsSync(filePath)) {
         const data = JSON.parse(readFileSync(filePath, 'utf8'));