@geraldmaron/construct 1.0.12 → 1.0.15

package/lib/intake/attribution.mjs

@@ -0,0 +1,77 @@
+/**
+ * lib/intake/attribution.mjs — provenance metadata for intake-archetype artifacts.
+ *
+ * Two-field attribution. Human identity comes from `git config user.name` +
+ * `user.email`; agent identity comes from CONSTRUCT_AGENT_ID (set by hosts
+ * like Claude Code, Codex, Copilot before they invoke the binary). Both are
+ * captured because either can be the proximate cause of a write and the
+ * audit reader needs to know which.
+ *
+ * Pure, side-effect free. No git/cli call when the env var
+ * CONSTRUCT_ATTRIBUTION_DISABLE=1 — useful for deterministic tests and for
+ * privacy-sensitive setups that prefer no identity capture.
+ */
+
+import { spawnSync } from 'node:child_process';
+
+function gitConfigValue(key, cwd) {
+  const result = spawnSync('git', ['config', '--get', key], {
+    cwd,
+    encoding: 'utf8',
+    timeout: 2000,
+  });
+  if (result.status !== 0) return null;
+  const value = (result.stdout || '').trim();
+  return value || null;
+}
+
+function humanIdentity(cwd) {
+  const name = gitConfigValue('user.name', cwd);
+  const email = gitConfigValue('user.email', cwd);
+  if (!name && !email) return null;
+  if (name && email) return `${name} <${email}>`;
+  return name || email;
+}
+
+function agentIdentity() {
+  return (
+    process.env.CONSTRUCT_AGENT_ID
+    || process.env.CLAUDE_AGENT_ID
+    || null
+  );
+}
+
+export function gatherAttribution({ now = new Date(), cwd } = {}) {
+  if (process.env.CONSTRUCT_ATTRIBUTION_DISABLE === '1') {
+    return {
+      createdBy: null,
+      createdByAgent: null,
+      createdAt: now.toISOString(),
+    };
+  }
+  return {
+    createdBy: humanIdentity(cwd),
+    createdByAgent: agentIdentity(),
+    createdAt: now.toISOString(),
+  };
+}
+
+export function stampAttribution(record, attribution = gatherAttribution()) {
+  if (!record || typeof record !== 'object') return record;
+  return {
+    ...record,
+    createdBy: attribution.createdBy,
+    createdByAgent: attribution.createdByAgent,
+    createdAt: attribution.createdAt,
+  };
+}
+
+export function touchAttribution(record, attribution = gatherAttribution()) {
+  if (!record || typeof record !== 'object') return record;
+  return {
+    ...record,
+    lastModifiedBy: attribution.createdBy,
+    lastModifiedByAgent: attribution.createdByAgent,
+    lastModifiedAt: attribution.createdAt,
+  };
+}

package/lib/intake/intake-config.mjs

@@ -44,6 +44,7 @@ export const DEFAULT_INTAKE_CONFIG = Object.freeze({
   maxDepth: INTAKE_DEFAULT_MAX_DEPTH,
   includeProjectInbox: true,
   includeDocsIntake: true,
+  includeArchetypeInbox: false,
 });
 
 export function intakeConfigPath(rootDir) {
@@ -98,6 +99,7 @@ export function loadIntakeConfig(rootDir, env = process.env) {
     maxDepth,
     includeProjectInbox: stored.includeProjectInbox !== false,
     includeDocsIntake: stored.includeDocsIntake !== false,
+    includeArchetypeInbox: stored.includeArchetypeInbox === true,
   };
 }
 
@@ -113,6 +115,7 @@ export function saveIntakeConfig(rootDir, patch = {}) {
     maxDepth: clampDepth(patch.maxDepth ?? current.maxDepth),
     includeProjectInbox: patch.includeProjectInbox !== undefined ? Boolean(patch.includeProjectInbox) : current.includeProjectInbox,
     includeDocsIntake: patch.includeDocsIntake !== undefined ? Boolean(patch.includeDocsIntake) : current.includeDocsIntake,
+    includeArchetypeInbox: patch.includeArchetypeInbox !== undefined ? Boolean(patch.includeArchetypeInbox) : current.includeArchetypeInbox,
   };
 
   const file = intakeConfigPath(rootDir);

package/lib/intake/manifest.mjs

@@ -0,0 +1,107 @@
+/**
+ * lib/intake/manifest.mjs — SHA-256 dedup manifest for intake-archetype projects.
+ *
+ * Projects that scaffold the intake archetype (profile.capabilities.intake)
+ * drop raw source files into `inbox/`. The manifest records which source
+ * files have already been processed (by content hash, not path) so the
+ * intake runtime can refuse to reprocess an unchanged file and so a moved
+ * or renamed file still dedups correctly.
+ *
+ * Storage: <projectRoot>/.cx/intake/manifest.json
+ *
+ * Shape:
+ *   {
+ *     "version": 1,
+ *     "files": {
+ *       "<sha256>": {
+ *         "sourcePath": "inbox/notes-2026-05-29.md",
+ *         "processedAt": "2026-05-29T19:00:00.000Z",
+ *         "intakeId": "intake-1779164832122-onxe",
+ *         "createdBy": "Gerald Dagher <gerald@example.com>",
+ *         "createdByAgent": "claude-opus-4-7"
+ *       }
+ *     }
+ *   }
+ *
+ * Pure functions over the JSON. Callers own the rootDir; no implicit cwd.
+ * Atomic writes go through write-rename so a crash mid-write cannot leave
+ * the manifest half-written.
+ */
+
+import { createHash } from 'node:crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+
+export const MANIFEST_REL_PATH = '.cx/intake/manifest.json';
+export const MANIFEST_VERSION = 1;
+
+function manifestPath(rootDir) {
+  return join(rootDir, MANIFEST_REL_PATH);
+}
+
+function emptyManifest() {
+  return { version: MANIFEST_VERSION, files: {} };
+}
+
+export function loadManifest(rootDir) {
+  const p = manifestPath(rootDir);
+  if (!existsSync(p)) return emptyManifest();
+  try {
+    const raw = JSON.parse(readFileSync(p, 'utf8'));
+    if (!raw || typeof raw !== 'object' || typeof raw.files !== 'object') {
+      return emptyManifest();
+    }
+    return raw;
+  } catch {
+    return emptyManifest();
+  }
+}
+
+export function saveManifest(rootDir, manifest) {
+  const p = manifestPath(rootDir);
+  const dir = join(rootDir, '.cx', 'intake');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const payload = JSON.stringify(manifest, null, 2) + '\n';
+  const tmp = `${p}.tmp`;
+  writeFileSync(tmp, payload, 'utf8');
+  renameSync(tmp, p);
+}
+
+export function sha256Of(buffer) {
+  return createHash('sha256').update(buffer).digest('hex');
+}
+
+export function hasFile(rootDir, sha) {
+  if (!sha) return false;
+  const manifest = loadManifest(rootDir);
+  return Boolean(manifest.files[sha]);
+}
+
+export function recordFile(rootDir, sha, entry) {
+  if (!sha) throw new Error('recordFile: sha is required');
+  const manifest = loadManifest(rootDir);
+  manifest.files[sha] = {
+    sourcePath: entry?.sourcePath ?? null,
+    processedAt: entry?.processedAt ?? new Date().toISOString(),
+    intakeId: entry?.intakeId ?? null,
+    createdBy: entry?.createdBy ?? null,
+    createdByAgent: entry?.createdByAgent ?? null,
+  };
+  saveManifest(rootDir, manifest);
+  return manifest.files[sha];
+}
+
+export function manifestStats(rootDir) {
+  const manifest = loadManifest(rootDir);
+  const entries = Object.values(manifest.files);
+  return {
+    total: entries.length,
+    version: manifest.version,
+  };
+}

package/lib/intake/poll-lock.mjs

@@ -0,0 +1,136 @@
+/**
+ * lib/intake/poll-lock.mjs — pid-stamped file lock around InboxWatcher.poll().
+ *
+ * Two pollers (the embed daemon and a manual `construct intake process`)
+ * share the same state file + manifest. Without serialization, both can
+ * decide a freshly-dropped file is unprocessed in the window between
+ * "read state" and "write state," producing two intake packets for one
+ * source. The lock makes one poll iteration atomic from the system's
+ * perspective: the second caller waits, retries until the timeout, or
+ * raises POLL_LOCK_BUSY for the CLI to render a clear refusal.
+ *
+ * Lockfile shape (JSON at <rootDir>/.cx/runtime/inbox-poll.lock):
+ *   { pid, actor, startedAt, timeoutAt? }
+ *
+ * Stale detection: a lock whose pid is gone, or whose timeoutAt has
+ * passed, is cleared on the next acquire attempt. Mirrors the
+ * lib/beads-lock.mjs API shape so callers familiar with one know the other.
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const POLL_LOCK_REL_PATH = '.cx/runtime/inbox-poll.lock';
+export const POLL_LOCK_BUSY = 'POLL_LOCK_BUSY';
+
+function lockPathFor(rootDir) {
+  return join(rootDir, POLL_LOCK_REL_PATH);
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function afterMs(ms) {
+  return new Date(Date.now() + ms).toISOString();
+}
+
+function processExists(pid) {
+  if (!pid || typeof pid !== 'number') return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function readPollLock(rootDir) {
+  const p = lockPathFor(rootDir);
+  if (!existsSync(p)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(p, 'utf8'));
+    if (!raw || typeof raw !== 'object') return null;
+    return raw;
+  } catch {
+    return null;
+  }
+}
+
+export function isPollLockStale(lock) {
+  if (!lock) return false;
+  if (lock.pid && !processExists(lock.pid)) return true;
+  if (lock.timeoutAt && new Date(lock.timeoutAt) < new Date()) return true;
+  return false;
+}
+
+function clearStale(rootDir) {
+  const lock = readPollLock(rootDir);
+  if (lock && isPollLockStale(lock)) {
+    rmSync(lockPathFor(rootDir), { force: true });
+    return true;
+  }
+  return false;
+}
+
+function writeLockFile(rootDir, lock) {
+  const p = lockPathFor(rootDir);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(lock, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Acquire the intake poll lock. Resolves with the lock object on success,
+ * rejects with an Error whose `code` is POLL_LOCK_BUSY when the wait window
+ * elapses without acquisition. The rejection's `holder` field carries the
+ * blocking lock's metadata for downstream error rendering.
+ */
+export async function acquirePollLock({
+  rootDir,
+  actor = 'unknown',
+  command = '',
+  waitMs = 0,
+  timeoutMs = 5 * 60 * 1000,
+  pollIntervalMs = 100,
+} = {}) {
+  if (!rootDir) throw new Error('acquirePollLock: rootDir is required');
+  const deadline = Date.now() + Math.max(0, waitMs);
+
+  while (true) {
+    clearStale(rootDir);
+    const existing = readPollLock(rootDir);
+    if (!existing) {
+      const lock = {
+        pid: process.pid,
+        actor,
+        command,
+        startedAt: nowIso(),
+        timeoutAt: timeoutMs > 0 ? afterMs(timeoutMs) : undefined,
+      };
+      writeLockFile(rootDir, lock);
+      return lock;
+    }
+    if (Date.now() >= deadline) {
+      const err = new Error(
+        `intake poll lock held by ${existing.actor || 'unknown'} (pid ${existing.pid}) since ${existing.startedAt}`,
+      );
+      err.code = POLL_LOCK_BUSY;
+      err.holder = existing;
+      throw err;
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+  }
+}
+
+/**
+ * Release the lock iff the calling process owns it. Returns true on release,
+ * false when the lock was missing, expired, or owned by someone else.
+ */
+export function releasePollLock(rootDir) {
+  const lock = readPollLock(rootDir);
+  if (lock && lock.pid === process.pid) {
+    rmSync(lockPathFor(rootDir), { force: true });
+    return true;
+  }
+  return false;
+}

package/lib/intake/prepare.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/intake/prepare.mjs — turn a fresh inbox ingestion into an R&D intake packet.
  *
- * Called by `InboxWatcher.poll()` after each successful file ingestion.
+ * Triggered by `InboxWatcher.poll()` after each successful file ingestion.
  * Four deterministic preparation steps, then write the result to the
  * intake queue:
  *
@@ -14,11 +14,16 @@
  *   4. Run classifyRdIntake to produce the R&D triage object (intake type,
  *      owner persona, recommended chain, action, risk).
  *
+ * After enqueue, fires a signal.promoted lifecycle event when the triage
+ * confidence crosses SIGNAL_PROMOTION_THRESHOLD (matches the default
+ * tag-vocabulary auto_threshold), so subscribers can act on confidently
+ * typed signals without polling the queue.
+ *
  * The agent — invoked manually or via session-start hook nudge — reads
  * the resulting `.cx/intake/pending/<id>.json` and does the real
  * comparison work (overlap with existing PRD? contradicts ADR? new RFC
- * candidate?). The daemon never calls an LLM. This separation keeps the
- * daemon cheap and predictable; the model spend stays with the agent.
+ * candidate?). The daemon never calls an LLM; the separation keeps the
+ * daemon cheap and predictable while model spend stays with the agent.
  */
 
 import { existsSync, readFileSync } from 'node:fs';
@@ -30,11 +35,19 @@ import { createIntakeQueue } from './queue.mjs';
 import { classifyRdIntake } from './classify.mjs';
 import { detectCustomerMentions, linkSignalToCustomer, updateCustomerProfile } from '../embed/customer-profiles.mjs';
 import { resolveActiveProfile } from '../profiles/loader.mjs';
+import { emitBestEffort as emitRoleEvent } from '../roles/event-bus.mjs';
+import { gatherAttribution, stampAttribution } from './attribution.mjs';
+import { MANIFEST_REL_PATH } from './manifest.mjs';
 
 const DEFAULT_RELATED_LIMIT = 5;
 const EXCERPT_CHARS = 800;
 const QUERY_CHARS = 500;
 
+// Confidence at which a triage signal is considered "promoted" from
+// uncertain to confidently classified. Mirrors the default tag-vocabulary
+// auto_threshold.
+const SIGNAL_PROMOTION_THRESHOLD = 0.70;
+
 export async function prepareIntakeForIngestedFile({
   rootDir,
   ingestedFile,
@@ -85,7 +98,7 @@ export async function prepareIntakeForIngestedFile({
 
   const droppedInfo = ingestedFile.droppedInfo ?? [];
 
-  const entry = {
+  const baseEntry = {
     intake: {
       sourcePath: ingestedFile.sourcePath,
       outputPath: ingestedFile.outputPath,
@@ -101,10 +114,35 @@ export async function prepareIntakeForIngestedFile({
     customers: customers.length ? customers : undefined,
   };
 
+  // Capability detection mirrors inbox.mjs: stamp provenance onto the packet
+  // when the project's intake manifest is present (init scaffolds it for
+  // archetype-enabled profiles). Keeps non-archetype packets shape-identical
+  // to the pre-attribution behavior so downstream consumers see no diff.
+
+  const archetypeOn = existsSync(`${rootDir}/${MANIFEST_REL_PATH}`);
+  const entry = archetypeOn ? stampAttribution(baseEntry, gatherAttribution({ cwd: rootDir })) : baseEntry;
+
   const intakeQueue = queue || createIntakeQueue(rootDir, env);
   const result = intakeQueue.enqueue(entry);
   const intakeId = result?.id || '';
 
+  // Promotion fires once a triage signal crosses the auto-classification
+  // threshold, giving subscribers a chance to act on a confidently typed
+  // signal without polling the intake queue.
+
+  if ((triage?.confidence ?? 0) >= SIGNAL_PROMOTION_THRESHOLD && triage?.intakeType && triage.intakeType !== 'unknown') {
+    emitRoleEvent('signal.promoted', {
+      summary: `${triage.intakeType} (${triage.confidence.toFixed(2)})`,
+      context: {
+        intakeId,
+        intakeType: triage.intakeType,
+        confidence: triage.confidence,
+        sourcePath: ingestedFile.sourcePath,
+        primaryOwner: triage.primaryOwner,
+      },
+    });
+  }
+
   // Update customer profiles with new evidence
   for (const mention of customerMentions) {
     try {

package/lib/knowledge/search.mjs

@@ -80,6 +80,18 @@ function buildSourceList(repoRoot = REPO_ROOT) {
     }
   }
 
+  // User-ingested documents (PDF/Office/audio routed through docling + whisper)
+  const ingestRoot = join(repoRoot, '.cx', 'ingest');
+  if (existsSync(ingestRoot)) {
+    for (const entry of readdirSync(ingestRoot)) {
+      const dir = join(ingestRoot, entry);
+      const markdown = join(dir, 'markdown.md');
+      if (!/^[a-f0-9]{64}$/.test(entry)) continue;
+      if (!existsSync(markdown)) continue;
+      sources.push({ path: markdown, rel: relative(repoRoot, markdown), priority: 4, source: 'ingest' });
+    }
+  }
+
   return sources;
 }