@geraldmaron/construct 1.0.2 → 1.0.4

package/lib/cli-commands.mjs

@@ -79,7 +79,13 @@ export const CLI_COMMANDS = [
     category: 'Core',
     core: true,
     description: 'Sync agent adapters to AI tools',
-    usage: 'construct sync',
+    usage: 'construct sync [--project] [--dry-run] [--no-docs] [--compress-personas]',
+    options: [
+      { flag: '--project', desc: 'Write project-local Claude adapters into the current repo only' },
+      { flag: '--dry-run', desc: 'Preview adapter changes without writing files' },
+      { flag: '--no-docs', desc: 'Skip AUTO docs regeneration after syncing adapters' },
+      { flag: '--compress-personas', desc: 'Write compressed runtime persona prompts without changing the source prompts' },
+    ],
   },
   {
     name: 'intake',
@@ -475,7 +481,7 @@ export const CLI_COMMANDS = [
     category: 'Advanced',
     core: false,
     description: 'Show version',
-    usage: 'construct version',
+    usage: 'construct version | construct --version',
   },
   {
     name: 'cleanup',

package/lib/document-ingest.mjs

@@ -77,7 +77,7 @@ function renderMarkdown({ sourcePath, extractedAt, title, extractionMethod, char
   return lines.join('\n');
 }
 
-function collectInputFiles(inputPath) {
+function collectInputFiles(inputPath, { maxDepth = 10 } = {}) {
   const resolvedPath = resolve(inputPath);
   if (!existsSync(resolvedPath)) throw new Error(`Input path not found: ${resolvedPath}`);
 
@@ -90,13 +90,14 @@ function collectInputFiles(inputPath) {
   if (!stat.isDirectory()) return [];
 
   const files = [];
-  const stack = [resolvedPath];
+  const stack = [{ path: resolvedPath, depth: 0 }];
   while (stack.length > 0) {
-    const current = stack.pop();
+    const { path: current, depth } = stack.pop();
+    if (depth >= maxDepth) continue;
     for (const entry of readdirSync(current, { withFileTypes: true })) {
       const full = join(current, entry.name);
       if (entry.isDirectory()) {
-        stack.push(full);
+        stack.push({ path: full, depth: depth + 1 });
         continue;
       }
       if (entry.isFile() && isExtractableDocumentPath(full)) files.push(full);
@@ -135,7 +136,7 @@ export async function ingestDocuments(inputPaths, {
     throw new Error('--out can only be used with a single input path');
   }
 
-  const files = inputPaths.flatMap((inputPath) => collectInputFiles(isAbsolute(inputPath) ? inputPath : resolve(cwd, inputPath)));
+  const files = inputPaths.flatMap((inputPath) => collectInputFiles(isAbsolute(inputPath) ? inputPath : resolve(cwd, inputPath), { maxDepth: 10 }));
   if (files.length === 0) {
     throw new Error('No supported document files found');
   }

package/lib/embed/cli.mjs

@@ -174,7 +174,7 @@ function parseArgs(args) {
 // Subcommand: start
 // ---------------------------------------------------------------------------
 
-async function cmdEmbedStart(args, { homeDir = os.homedir(), rootDir } = {}) {
+async function cmdEmbedStart(args, { homeDir = os.homedir(), rootDir, _workerPath, _livenessCheckMs = 400 } = {}) {
   const existing = readRunningState(homeDir);
   if (existing) {
     process.stdout.write(`embed daemon already running (pid ${existing.pid})\n`);
@@ -188,7 +188,11 @@ async function cmdEmbedStart(args, { homeDir = os.homedir(), rootDir } = {}) {
       ? path.join(os.homedir(), '.construct', 'embed.yaml')
       : null;
 
-  const workerPath = path.join(rootDir, 'lib', 'embed', 'worker.mjs');
+  const workerPath = _workerPath ?? path.join(rootDir, 'lib', 'embed', 'worker.mjs');
+  if (!fs.existsSync(workerPath)) {
+    throw new Error(`embed worker not found at ${workerPath}`);
+  }
+
   const workerArgs = configPath ? [workerPath, '--config', configPath] : [workerPath];
   const log = logPath(homeDir);
   fs.mkdirSync(path.dirname(log), { recursive: true });
@@ -199,9 +203,18 @@ async function cmdEmbedStart(args, { homeDir = os.homedir(), rootDir } = {}) {
     stdio: ['ignore', fd, fd],
     env: { ...process.env },
   });
+  fs.closeSync(fd);
   child.unref();
 
   writeState({ pid: child.pid, configPath: configPath ?? 'auto', startedAt: new Date().toISOString() }, homeDir);
+
+  // Brief liveness check — detects immediate crashes (e.g. missing module, bad config path)
+  await new Promise(r => setTimeout(r, _livenessCheckMs));
+  if (!processExists(child.pid)) {
+    clearState(homeDir);
+    throw new Error(`embed worker (pid ${child.pid}) exited immediately — check ${log}`);
+  }
+
   process.stdout.write(`embed daemon started (pid ${child.pid})\n`);
   process.stdout.write(`config: ${configPath ?? 'auto-discover from config.env'}\n`);
   process.stdout.write(`log:    ${log}\n`);
@@ -299,7 +312,7 @@ export async function runEmbedCli(args, opts = {}) {
   const rootDir = opts.rootDir ?? new URL('../..', import.meta.url).pathname;
 
   switch (sub) {
-    case 'start':       return cmdEmbedStart(subArgs, { homeDir, rootDir });
+    case 'start':       return cmdEmbedStart(subArgs, { homeDir, rootDir, _workerPath: opts._workerPath, _livenessCheckMs: opts._livenessCheckMs });
     case 'stop':        return cmdEmbedStop(subArgs, { homeDir });
     case 'status':      return cmdEmbedStatus(subArgs, { homeDir });
     case 'snapshot':    return cmdEmbedSnapshot(subArgs, { homeDir });

package/lib/embed/conflict-detection.mjs

@@ -11,18 +11,33 @@
  *   2. Contradiction detection — new signal contradicts a documented decision
  *
  * Storage:
- *   ~/.cx/product-intel/artifact-index.json — cached artifact embeddings
+ *   ~/.cx/knowledge/reference/artifact-index.json — cached artifact embeddings
  *   Rebuilt on first use or when artifact file count changes.
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, renameSync } from 'node:fs';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
 import { embed, cosineSimilarity, extractTextFromPacket } from './semantic.mjs';
 import { listArtifacts } from './artifact.mjs';
+import { cxDir } from '../paths.mjs';
+import { knowledgeReferenceStore } from '../knowledge/layout.mjs';
 
-const INDEX_DIR = join(homedir(), '.cx', 'product-intel');
-const INDEX_FILE = join(INDEX_DIR, 'artifact-index.json');
+function migrateLegacyIndex(indexFile, legacyFile) {
+  if (existsSync(indexFile) || !existsSync(legacyFile)) return;
+  mkdirSync(join(indexFile, '..'), { recursive: true });
+  try { renameSync(legacyFile, indexFile); } catch { /* compatibility-only */ }
+}
+
+function indexPaths({ migrate = false } = {}) {
+  const indexDir = join(cxDir(), knowledgeReferenceStore());
+  const legacyFile = join(cxDir(), 'product-intel', 'artifact-index.json');
+  const indexFile = join(indexDir, 'artifact-index.json');
+  if (migrate) migrateLegacyIndex(indexFile, legacyFile);
+  return {
+    indexDir,
+    indexFile,
+  };
+}
 
 const OVERLAP_THRESHOLD = 0.6;
 const CONTRADICTION_THRESHOLD = 0.7;
@@ -32,7 +47,8 @@ const STALE_INDEX_HOURS = 24;
  * Ensure index directory exists.
  */
 function ensureDir() {
-  if (!existsSync(INDEX_DIR)) mkdirSync(INDEX_DIR, { recursive: true });
+  const { indexDir } = indexPaths({ migrate: true });
+  if (!existsSync(indexDir)) mkdirSync(indexDir, { recursive: true });
 }
 
 let _artifactIndex = null;
@@ -55,9 +71,10 @@ export async function buildArtifactIndex({ rootDir, forceRebuild = false } = {})
   const cacheHash = cacheKey.length;
 
   // Check if cached index is fresh
-  if (!forceRebuild && existsSync(INDEX_FILE)) {
+  const { indexFile } = indexPaths();
+  if (!forceRebuild && existsSync(indexFile)) {
     try {
-      const cached = JSON.parse(readFileSync(INDEX_FILE, 'utf8'));
+      const cached = JSON.parse(readFileSync(indexFile, 'utf8'));
       if (cached.cacheHash === cacheHash && cached.index?.length === artifacts.length) {
         const age = Date.now() - new Date(cached.builtAt).getTime();
         if (age < STALE_INDEX_HOURS * 60 * 60 * 1000) {
@@ -96,7 +113,7 @@ export async function buildArtifactIndex({ rootDir, forceRebuild = false } = {})
     embedding: a.embedding ? Array.from(a.embedding) : null,
   }));
 
-  writeFileSync(INDEX_FILE, JSON.stringify({
+  writeFileSync(indexFile, JSON.stringify({
     cacheHash,
     builtAt: new Date().toISOString(),
     artifactCount: artifacts.length,

package/lib/embed/customer-profiles.mjs

@@ -1,31 +1,47 @@
 /**
  * lib/embed/customer-profiles.mjs — Global customer profile store.
  *
- * Maintains durable customer/account memory in ~/.cx/product-intel/customer-profiles/.
+ * Maintains durable customer/account memory in ~/.cx/knowledge/internal/customer-profiles/.
  * Profiles are additive — history is preserved unless explicitly deleted.
- * Used by intake triage to link signals to customers and detect account-level patterns.
+ * Links signals to customers and detects account-level patterns during intake triage.
  *
  * Storage:
- *   ~/.cx/product-intel/customer-profiles/<customer-id>.md
- *   ~/.cx/product-intel/customer-profiles/index.json — quick lookup by name/email
+ *   ~/.cx/knowledge/internal/customer-profiles/<customer-id>.md
+ *   ~/.cx/knowledge/internal/customer-profiles/index.json — quick lookup by name/email
  *
  * Each profile follows templates/docs/customer-profile.md schema.
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, appendFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, appendFileSync, renameSync } from 'node:fs';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
-import { homedir } from 'node:os';
+import { cxDir } from '../paths.mjs';
+import { knowledgeInternalStore } from '../knowledge/layout.mjs';
 
-const PROFILES_DIR = join(homedir(), '.cx', 'product-intel', 'customer-profiles');
-const INDEX_FILE = join(PROFILES_DIR, 'index.json');
+function migrateLegacyDir(modernDir, legacyDir) {
+  if (existsSync(modernDir) || !existsSync(legacyDir)) return;
+  mkdirSync(join(modernDir, '..'), { recursive: true });
+  try { renameSync(legacyDir, modernDir); } catch { /* compatibility-only */ }
+}
+
+function profilePaths({ migrate = false } = {}) {
+  const modernDir = join(cxDir(), knowledgeInternalStore('customer-profiles'));
+  const legacyDir = join(cxDir(), 'product-intel', 'customer-profiles');
+  if (migrate) migrateLegacyDir(modernDir, legacyDir);
+  const profilesDir = existsSync(modernDir) || !existsSync(legacyDir) ? modernDir : legacyDir;
+  return {
+    profilesDir,
+    indexFile: join(profilesDir, 'index.json'),
+  };
+}
 
 /**
  * Ensure profile directory exists.
  */
 function ensureDir() {
-  if (!existsSync(PROFILES_DIR)) {
-    mkdirSync(PROFILES_DIR, { recursive: true });
+  const { profilesDir } = profilePaths({ migrate: true });
+  if (!existsSync(profilesDir)) {
+    mkdirSync(profilesDir, { recursive: true });
   }
 }
 
@@ -34,9 +50,10 @@ function ensureDir() {
  * @returns {{ [key: string]: { id: string, name: string, status: string, updatedAt: string } }}
  */
 function readIndex() {
-  if (!existsSync(INDEX_FILE)) return {};
+  const { indexFile } = profilePaths();
+  if (!existsSync(indexFile)) return {};
   try {
-    return JSON.parse(readFileSync(INDEX_FILE, 'utf8'));
+    return JSON.parse(readFileSync(indexFile, 'utf8'));
   } catch (err) {
     process.stderr.write('[customer-profiles.mjs] readIndex: ' + (err?.message ?? String(err)) + '\n');
     return {};
@@ -48,8 +65,9 @@ function readIndex() {
  * @param {object} index
  */
 function writeIndex(index) {
+  const { indexFile } = profilePaths();
   ensureDir();
-  writeFileSync(INDEX_FILE, JSON.stringify(index, null, 2) + '\n');
+  writeFileSync(indexFile, JSON.stringify(index, null, 2) + '\n');
 }
 
 /**
@@ -95,7 +113,7 @@ export function createCustomerProfile({ name, owner, workspace, status = 'active
   const id = generateCustomerId();
   const slug = slugify(name);
   const filename = `${slug}-${id}.md`;
-  const filePath = join(PROFILES_DIR, filename);
+  const filePath = join(profilePaths().profilesDir, filename);
 
   const date = new Date().toISOString().slice(0, 10);
   const profile = {
@@ -219,12 +237,13 @@ TODO
  */
 export function getCustomerProfile(customerId) {
   ensureDir();
+  const { profilesDir } = profilePaths();
 
   // Try direct lookup by ID in filename
-  const files = readdirSync(PROFILES_DIR).filter(f => f.endsWith('.md'));
+  const files = readdirSync(profilesDir).filter(f => f.endsWith('.md'));
   for (const file of files) {
     if (file.includes(customerId)) {
-      const filePath = join(PROFILES_DIR, file);
+      const filePath = join(profilesDir, file);
       return parseProfileFile(filePath);
     }
   }
@@ -239,6 +258,7 @@ export function getCustomerProfile(customerId) {
  */
 export function searchCustomerProfiles(query) {
   ensureDir();
+  const { profilesDir } = profilePaths();
 
   const index = readIndex();
   const querySlug = slugify(query);
@@ -268,7 +288,7 @@ export function searchCustomerProfiles(query) {
             id: entry.id,
             name: entry.name,
             status: entry.status,
-            path: join(PROFILES_DIR, `${slugify(entry.name)}-${entry.id}.md`),
+            path: join(profilesDir, `${slugify(entry.name)}-${entry.id}.md`),
           });
         }
       }
@@ -328,7 +348,7 @@ export function updateCustomerProfile(customerId, updates) {
     throw new Error(`Customer profile not found: ${customerId}`);
   }
 
-  const filePath = join(PROFILES_DIR, `${slugify(profile.name)}-${customerId}.md`);
+  const filePath = join(profilePaths().profilesDir, `${slugify(profile.name)}-${customerId}.md`);
   let content = readFileSync(filePath, 'utf8');
   const date = new Date().toISOString().slice(0, 10);
 

package/lib/embed/daemon.mjs

@@ -58,8 +58,8 @@ function logCatch(source, err) {
 
 /**
  * Resolve an LLM API key from multiple sources: env → config.env → ~/.env → shell rc.
- * Used by the telemetry-generation probe so it can find keys stored via 1Password
- * op:// refs in .zshrc or other shell config files.
+ * Supports 1Password op:// refs in .zshrc or other shell config files for the
+ * telemetry-generation probe.
  */
 async function resolveLLMKey(varName, env) {
   if (env[varName] && typeof env[varName] === 'string' && env[varName].length > 0) return env[varName];
@@ -467,15 +467,16 @@ export class EmbedDaemon {
           process.stderr.write(`[embed] Distilled ${itemsWritten} snapshot item(s) into observation store\n`);
         }
 
-        // Regenerate roadmap each tick so .cx/roadmap.md stays current and the
-        // missing-focal-resource gap clears on the next snapshot.
-        try {
-          const roadmap = generateRoadmap({ targetPath: this.#rootDir, snapshot, roles: this.#config?.roles });
-          if (!roadmap.skipped) {
-            process.stderr.write(`[embed] Roadmap refreshed: ${roadmap.itemCount} open item(s) → ${roadmap.path}\n`);
+        // Regenerate roadmap each tick unless disabled by the host config.
+        if (process.env.CONSTRUCT_EMBED_ROADMAP_ENABLED !== '0') {
+          try {
+            const roadmap = generateRoadmap({ targetPath: this.#rootDir, snapshot, roles: this.#config?.roles });
+            if (!roadmap.skipped) {
+              process.stderr.write(`[embed] Roadmap refreshed: ${roadmap.itemCount} open item(s) → ${roadmap.path}\n`);
+            }
+          } catch (err) {
+            process.stderr.write(`[embed] Roadmap refresh failed: ${err.message}\n`);
           }
-        } catch (err) {
-          process.stderr.write(`[embed] Roadmap refresh failed: ${err.message}\n`);
         }
       },
       { runImmediately: true },
@@ -575,7 +576,8 @@ this.#scheduler.register(
         const ok = result.results.filter(r => r.success).length;
         const total = result.results.length;
         process.stderr.write(`[embed] Telemetry setup: ${ok}/${total} resources configured\n`);
-      } else if (!result.ok) {
+      } else if (!result.ok && !result.error?.includes('required')) {
+        // Suppress the "keys required" message — normal for solo mode without telemetry configured.
         process.stderr.write(`[embed] Telemetry setup skipped: ${result.error}\n`);
       } else if (result.results?.some(r => !r.success)) {
         const failures = result.results.filter(r => !r.success);
@@ -743,6 +745,7 @@ this.#scheduler.register(
       'roadmap',
       60 * 60_000,
       async () => {
+        if (process.env.CONSTRUCT_EMBED_ROADMAP_ENABLED === '0') return;
         if (!this.#lastSnapshot) return; // wait until at least one snapshot exists
         try {
           const result = generateRoadmap({ targetPath: this.#rootDir, snapshot: this.#lastSnapshot, roles: this.#config?.roles });
@@ -840,21 +843,23 @@ this.#scheduler.register(
               meta: { gaps: result.gaps.length, conflicts: result.conflicts?.length || 0, recommendations: result.recommendations?.length || 0, autoFixed, queued },
             });
           }
-          emitTraceEvent({
-            rootDir: this.#rootDir,
-            eventType: 'lifecycle.completed',
-            traceId: this.#daemonTraceId,
-            spanId: newSpanId(),
-            env: this.#env,
-            metadata: {
-              gaps: result.gaps.length,
-              conflicts: result.conflicts?.length || 0,
-              recommendations: result.recommendations?.length || 0,
-              autoFixed,
-              queued,
-              targets: result.targets,
-            },
-          }).catch(() => {});
+          try {
+            emitTraceEvent({
+              rootDir: this.#rootDir,
+              eventType: 'lifecycle.completed',
+              traceId: this.#daemonTraceId,
+              spanId: newSpanId(),
+              env: this.#env,
+              metadata: {
+                gaps: result.gaps.length,
+                conflicts: result.conflicts?.length || 0,
+                recommendations: result.recommendations?.length || 0,
+                autoFixed,
+                queued,
+                targets: result.targets,
+              },
+            });
+          } catch { /* observability must not break the caller */ }
         } catch (err) {
           process.stderr.write(`[embed] Docs lifecycle error: ${err.message}\n`);
         }
@@ -1114,18 +1119,20 @@ this.#scheduler.register(
 
     this.#status = 'running';
     this.#daemonTraceId = newTraceId();
-    emitTraceEvent({
-      rootDir: this.#rootDir,
-      eventType: 'daemon.started',
-      traceId: this.#daemonTraceId,
-      spanId: newSpanId(),
-      env: this.#env,
-      metadata: {
-        pid: process.pid,
-        configSnapshotIntervalMs: this.#config.snapshot.intervalMs,
-        version: process.env.CONSTRUCT_VERSION || '0.0.0',
-      },
-    }).catch(() => {});
+    try {
+      emitTraceEvent({
+        rootDir: this.#rootDir,
+        eventType: 'daemon.started',
+        traceId: this.#daemonTraceId,
+        spanId: newSpanId(),
+        env: this.#env,
+        metadata: {
+          pid: process.pid,
+          configSnapshotIntervalMs: this.#config.snapshot.intervalMs,
+          version: process.env.CONSTRUCT_VERSION || '0.0.0',
+        },
+      });
+    } catch { /* observability must not break the caller */ }
     process.stderr.write(`[embed] Daemon started. Snapshot interval: ${this.#config.snapshot.intervalMs}ms\n`);
   }
 
@@ -1134,14 +1141,16 @@ this.#scheduler.register(
     this.#inboxLiveWatcher = null;
     this.#scheduler?.stop();
     this.#status = 'stopped';
-    emitTraceEvent({
-      rootDir: this.#rootDir,
-      eventType: 'daemon.stopped',
-      traceId: this.#daemonTraceId,
-      spanId: newSpanId(),
-      env: this.#env,
-      metadata: { pid: process.pid, uptimeMs: process.uptime() * 1000 },
-    }).catch(() => {});
+    try {
+      emitTraceEvent({
+        rootDir: this.#rootDir,
+        eventType: 'daemon.stopped',
+        traceId: this.#daemonTraceId,
+        spanId: newSpanId(),
+        env: this.#env,
+        metadata: { pid: process.pid, uptimeMs: process.uptime() * 1000 },
+      });
+    } catch { /* observability must not break the caller */ }
     process.stderr.write('[embed] Daemon stopped.\n');
   }
 
@@ -1182,10 +1191,10 @@ this.#scheduler.register(
      try {
        // Query strategy/PRDs/RFCs from knowledge base
        
-       const strategyDocs = searchObservations(this.#rootDir, 'PRD RFC strategy', {
-         category: 'knowledge',
-         limit: 50,
-       });
+        const strategyDocs = searchObservations(this.#rootDir, 'PRD RFC strategy', {
+          category: 'insight',
+          limit: 50,
+        });
        
        // Query existing Jira tickets via Atlassian provider
        

package/lib/embed/inbox.mjs

@@ -36,6 +36,7 @@ const STATE_FILE = '.cx/runtime/inbox-state.json';
 const DEFAULT_INBOX_SUBDIR = '.cx/inbox';
 const DOCS_INTAKE_SUBDIR = 'docs/intake';
 const MAX_FILE_SIZE_BYTES = 50 * 1024 * 1024; // 50 MB hard cap
+const STALE_STATE_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 
 function nextAvailablePath(targetPath) {
   if (!existsSync(targetPath)) return targetPath;
@@ -50,6 +51,28 @@ function nextAvailablePath(targetPath) {
   }
 }
 
+// ─── Stale state pruning ─────────────────────────────────────────────────────
+
+/**
+ * Remove state entries for source files absent from disk for more than 7 days.
+ * Returns the count of removed entries.
+ */
+function pruneStaleState(rootDir, state) {
+  const cutoffMs = Date.now() - STALE_STATE_AGE_MS;
+  let removed = 0;
+  for (const key of Object.keys(state)) {
+    const entry = state[key];
+    if (!existsSync(key) && entry.processedAt) {
+      const processedMs = new Date(entry.processedAt).getTime();
+      if (processedMs < cutoffMs) {
+        delete state[key];
+        removed++;
+      }
+    }
+  }
+  return removed;
+}
+
 // ─── State helpers ────────────────────────────────────────────────────────────
 
 function statePath(rootDir) {
@@ -327,6 +350,13 @@ export class InboxWatcher {
       }
     }
 
+    // Prune stale state entries: remove entries for source files absent from disk
+    // for more than 7 days (covers moved/renamed files that linger in state).
+    const staleRemoved = pruneStaleState(this.#rootDir, state);
+    if (staleRemoved > 0) {
+      process.stderr.write(`[inbox] pruned ${staleRemoved} stale state entries\n`);
+    }
+
     if (processed.length || errors.length) {
       writeState(this.#rootDir, state);
     }