@geraldmaron/construct 1.0.6 → 1.0.8

package/lib/daemons/contract.mjs

@@ -0,0 +1,210 @@
+/**
+ * lib/daemons/contract.mjs — Shared safeguard contract for every long-running
+ * Construct process. No ambient process in Construct survives without these
+ * rails.
+ *
+ * Safeguards enforced for every daemon that uses DaemonRunner:
+ *   - Bounded lifetime: max wall-clock runtime (default 24h) before self-restart
+ *     with state checkpoint.
+ *   - Idle shutdown: if no work for N consecutive ticks, stop and log;
+ *     resume on next external trigger.
+ *   - Heartbeat: every tick writes lastTickAt to a known path.
+ *   - Single-writer lock: prevents duplicate daemon instances; auto-expires.
+ *   - Killswitch: env var disables the daemon without code changes.
+ *   - Resource caps: CPU/memory limits via process.resourceUsage thresholds.
+ *
+ * Per-item safeguards (TTL, retry budget, dead-letter) are owned by the work
+ * queue, not the runner; this module exposes a small queue helper for that.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+
+export const DEFAULT_MAX_RUNTIME_MS = 24 * 60 * 60 * 1000;
+export const DEFAULT_IDLE_TICKS = 6;
+export const DEFAULT_MEMORY_CAP_MB = 256;
+
+/**
+ * Build a DaemonRunner. Spec fields:
+ *   name              — identifier; used in heartbeat path
+ *   tick(ctx)         — async; returns { didWork: boolean } each cycle
+ *   intervalMs        — sleep between ticks
+ *   killswitchEnv     — process.env key; when '=off' the daemon refuses to start
+ *   heartbeatPath     — file written each tick with { ts, name, ticks }
+ *   lockPath          — single-writer lockfile (defaults to heartbeatPath + .lock)
+ *   maxRuntimeMs      — bounded lifetime; default 24h
+ *   maxIdleTicks      — consecutive zero-work ticks before idle shutdown
+ *   memoryCapMb       — RSS cap; exceeding triggers self-stop + escalation
+ *   onIdleShutdown    — optional callback when the runner stops due to idle
+ *   onMemoryExceeded  — optional callback when the runner stops due to memory
+ */
+export function createDaemon(spec) {
+  if (!spec?.name) throw new Error('daemon spec missing name');
+  if (typeof spec.tick !== 'function') throw new Error('daemon spec missing tick(ctx)');
+
+  const cfg = {
+    intervalMs: spec.intervalMs ?? 60_000,
+    killswitchEnv: spec.killswitchEnv,
+    heartbeatPath: spec.heartbeatPath,
+    lockPath: spec.lockPath || (spec.heartbeatPath ? `${spec.heartbeatPath}.lock` : null),
+    maxRuntimeMs: spec.maxRuntimeMs ?? DEFAULT_MAX_RUNTIME_MS,
+    maxIdleTicks: spec.maxIdleTicks ?? DEFAULT_IDLE_TICKS,
+    memoryCapMb: spec.memoryCapMb ?? DEFAULT_MEMORY_CAP_MB,
+    onIdleShutdown: spec.onIdleShutdown,
+    onMemoryExceeded: spec.onMemoryExceeded,
+  };
+
+  let running = false;
+  let stopRequested = false;
+  let startedAt = 0;
+  let ticks = 0;
+  let idleTicks = 0;
+
+  function killswitchEngaged() {
+    if (!cfg.killswitchEnv) return false;
+    return process.env[cfg.killswitchEnv] === 'off' || process.env[cfg.killswitchEnv] === '0';
+  }
+
+  function acquireLock() {
+    if (!cfg.lockPath) return true;
+    try { mkdirSync(dirname(cfg.lockPath), { recursive: true }); } catch { /* ignore */ }
+    try {
+      writeFileSync(cfg.lockPath, JSON.stringify({ pid: process.pid, startedAt: Date.now() }), { flag: 'wx' });
+      return true;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      const holder = readLockHolder();
+      if (holder && processAlive(holder.pid)) return false;
+      // Stale lock — steal it
+      writeFileSync(cfg.lockPath, JSON.stringify({ pid: process.pid, startedAt: Date.now() }), { flag: 'w' });
+      return true;
+    }
+  }
+
+  function releaseLock() {
+    if (!cfg.lockPath) return;
+    try { unlinkSync(cfg.lockPath); } catch { /* ignore */ }
+  }
+
+  function readLockHolder() {
+    if (!cfg.lockPath || !existsSync(cfg.lockPath)) return null;
+    try { return JSON.parse(readFileSync(cfg.lockPath, 'utf8')); } catch { return null; }
+  }
+
+  function processAlive(pid) {
+    if (!pid) return false;
+    try { process.kill(pid, 0); return true; } catch { return false; }
+  }
+
+  function heartbeat() {
+    if (!cfg.heartbeatPath) return;
+    try { mkdirSync(dirname(cfg.heartbeatPath), { recursive: true }); } catch { /* ignore */ }
+    try {
+      writeFileSync(cfg.heartbeatPath, JSON.stringify({
+        name: spec.name, pid: process.pid, ts: Date.now(), ticks, idleTicks,
+      }));
+    } catch { /* heartbeat is best effort */ }
+  }
+
+  function memoryExceeded() {
+    const rssMb = process.memoryUsage().rss / (1024 * 1024);
+    return rssMb > cfg.memoryCapMb;
+  }
+
+  async function run() {
+    if (killswitchEngaged()) {
+      return { stopped: true, reason: 'killswitch' };
+    }
+    if (!acquireLock()) {
+      return { stopped: true, reason: 'lock-held' };
+    }
+
+    running = true;
+    stopRequested = false;
+    startedAt = Date.now();
+    ticks = 0;
+    idleTicks = 0;
+
+    try {
+      while (running && !stopRequested) {
+        if (Date.now() - startedAt >= cfg.maxRuntimeMs) {
+          return { stopped: true, reason: 'max-runtime', ticks };
+        }
+        if (memoryExceeded()) {
+          if (cfg.onMemoryExceeded) try { await cfg.onMemoryExceeded(); } catch { /* ignore */ }
+          return { stopped: true, reason: 'memory-cap', ticks };
+        }
+        if (killswitchEngaged()) {
+          return { stopped: true, reason: 'killswitch-mid-run', ticks };
+        }
+
+        ticks++;
+        let result;
+        try { result = await spec.tick({ ticks, idleTicks }); }
+        catch (err) { result = { didWork: false, error: err.message }; }
+
+        heartbeat();
+
+        if (result?.didWork) idleTicks = 0;
+        else idleTicks++;
+
+        if (idleTicks >= cfg.maxIdleTicks) {
+          if (cfg.onIdleShutdown) try { await cfg.onIdleShutdown(); } catch { /* ignore */ }
+          return { stopped: true, reason: 'idle', ticks };
+        }
+
+        await sleep(cfg.intervalMs);
+      }
+      return { stopped: true, reason: 'requested', ticks };
+    } finally {
+      running = false;
+      releaseLock();
+    }
+  }
+
+  function stop() { stopRequested = true; }
+
+  function status() {
+    return {
+      name: spec.name,
+      running,
+      ticks,
+      idleTicks,
+      uptimeMs: running ? Date.now() - startedAt : 0,
+      heartbeatPath: cfg.heartbeatPath,
+      lockPath: cfg.lockPath,
+    };
+  }
+
+  return { run, stop, status };
+}
+
+/**
+ * Inspect a heartbeat file written by a DaemonRunner. Returns the heartbeat
+ * if fresh (within staleMs), null if stale or missing.
+ */
+export function readHeartbeat(heartbeatPath, { staleMs = 5 * 60 * 1000 } = {}) {
+  if (!heartbeatPath || !existsSync(heartbeatPath)) return null;
+  try {
+    const data = JSON.parse(readFileSync(heartbeatPath, 'utf8'));
+    const age = Date.now() - (data.ts || 0);
+    if (age > staleMs) return null;
+    return { ...data, ageMs: age };
+  } catch { return null; }
+}
+
+/**
+ * Helper for per-item TTL + retry + dead-letter routing inside a tick. Given
+ * a packet with `firstSeenAt` and optional `attempts`, returns a routing
+ * decision: 'process' (within budget), 'dead-letter' (TTL or retry budget
+ * exhausted), or 'escalate' (past TTL but not yet retried max).
+ */
+export function classifyPacket(packet, { maxAgeMs = 14 * 24 * 60 * 60 * 1000, maxAttempts = 3 } = {}) {
+  const firstSeenAt = packet?.firstSeenAt || packet?.createdAt || Date.now();
+  const attempts = packet?.attempts || 0;
+  const age = Date.now() - new Date(firstSeenAt).getTime();
+  if (age > maxAgeMs) return { route: 'dead-letter', reason: 'ttl-exceeded' };
+  if (attempts >= maxAttempts) return { route: 'dead-letter', reason: 'retry-budget-exhausted' };
+  return { route: 'process', attempts };
+}

package/lib/distill.mjs

@@ -11,6 +11,7 @@ import { join, extname, relative, dirname, basename } from 'path';
 import { execSync, spawnSync } from 'child_process';
 import { homedir } from 'os';
 import { getActiveOverlays } from './headhunt.mjs';
+import { withGenAiSpan, GenAiAttrs } from './telemetry/otel-tracer.mjs';
 import {
   EXTRACTABLE_DOCUMENT_EXTS,
   UTF8_TEXT_EXTS,
@@ -355,10 +356,27 @@ export async function distill(dir, { format = 'summary', query = '', mode = 'aut
   }
 
   process.stderr.write('   Invoking claude --print …\n\n');
-  const result = spawnSync('claude', ['--print', prompt], {
-    encoding: 'utf8',
-    maxBuffer: 10 * 1024 * 1024,
-    timeout: 120_000,
+  const result = await withGenAiSpan('chat', {
+    [GenAiAttrs.SYSTEM]: 'anthropic',
+    [GenAiAttrs.OPERATION_NAME]: 'chat',
+    [GenAiAttrs.REQUEST_MODEL]: process.env.CONSTRUCT_MODEL || 'claude-3-5-sonnet',
+    'construct.operation': 'distill',
+    'construct.prompt_chars': prompt.length,
+  }, async (span) => {
+    const r = spawnSync('claude', ['--print', prompt], {
+      encoding: 'utf8',
+      maxBuffer: 10 * 1024 * 1024,
+      timeout: 120_000,
+    });
+    if (r.error) throw r.error;
+    if (r.status !== 0) {
+      const errOut = r.stderr || '';
+      if (errOut) process.stderr.write(`${errOut}\n`);
+      throw new Error(`claude exited with status ${r.status}`);
+    }
+    const out = r.stdout || '';
+    span.setAttribute(GenAiAttrs.USAGE_OUTPUT_TOKENS, Math.ceil(out.length / 4));
+    return r;
   });
 
   if (result.error) throw result.error;

package/lib/doc-stamp.mjs

@@ -7,6 +7,7 @@
  *   stampFrontmatter  — inject/update audit block at top of a markdown string
  *   verifyStamp       — verify body_hash against current content
  *   parseStamp        — extract stamp fields from a document string
+ *   validateTags      — validate frontmatter tags against a loaded vocabulary
  *
  * Design:
  *   - Zero npm dependencies (Node built-ins only)
@@ -16,9 +17,12 @@
  *     trimmed, so whitespace-only edits do not break verification.
  *   - generator field is intentionally short (no version pinning) so the
  *     stamp survives construct upgrades without false-positive hash mismatches.
+ *   - validateTags does NOT throw: it returns { errors, warnings } for callers
+ *     to decide how to handle violations.
  */
 
 import { createHash, randomBytes } from 'node:crypto';
+import { validateTags as vocabValidateTags, isTagDeprecated, isTagArchived } from './tags/vocabulary.mjs';
 
 // ---------------------------------------------------------------------------
 // UUIDv7 — RFC 9562 §5.7
@@ -147,6 +151,50 @@ export function parseStamp(content) {
   return fields;
 }
 
+// ---------------------------------------------------------------------------
+// Tag validation — uses vocabulary module, returns errors/warnings for callers
+// ---------------------------------------------------------------------------
+
+/**
+ * Validates frontmatter tags against a loaded vocabulary object.
+ * Returns { errors: string[], warnings: string[] }.
+ *
+ * Errors (hard violations):
+ *   - Two or more tags from the same exclusive facet (duplicateFacets)
+ *   - Writing a tag with status 'archived'
+ *
+ * Warnings (soft violations):
+ *   - Tag ID not found in vocabulary (unknown)
+ *   - Writing a tag with status 'deprecated'
+ */
+export function validateTags(frontmatter, vocab) {
+  const tags = Array.isArray(frontmatter.tags) ? frontmatter.tags : [];
+  const errors = [];
+  const warnings = [];
+
+  if (tags.length === 0) return { errors, warnings };
+
+  const { unknown, duplicateFacets } = vocabValidateTags(tags, vocab);
+
+  for (const id of duplicateFacets) {
+    errors.push(`exclusive-facet violation: tag "${id}" shares a facet with an earlier tag`);
+  }
+
+  for (const id of unknown) {
+    warnings.push(`unknown tag: "${id}" is not in the controlled vocabulary`);
+  }
+
+  for (const id of tags) {
+    if (isTagArchived(id, vocab)) {
+      errors.push(`archived-tag write: tag "${id}" has status archived and must not be applied`);
+    } else if (isTagDeprecated(id, vocab)) {
+      warnings.push(`deprecated-tag write: tag "${id}" has status deprecated`);
+    }
+  }
+
+  return { errors, warnings };
+}
+
 /**
  * Verify that the stored body_hash matches the current body.
  * Returns { valid: true } or { valid: false, reason, stored, computed }.

package/lib/docs-verify.mjs

@@ -4,9 +4,11 @@
  *
  * Checks:
  * 1. README.md exists and has basic sections
- * 2. AGENTS.md exists and has required sections  
+ * 2. AGENTS.md exists and has required sections
  * 3. plan.md exists and is current (< 7 days)
- * 4. .cx/context.md exists and is current (< 7 days)
+ * 4. .cx/context.md is current (< 7 days, critical when .cx/ exists). Verifier
+ *    reconstitutes the file from the init template when .cx/ exists but the
+ *    file does not — invariant enforcement is centralized here.
  * 5. docs/README.md exists (if docs system initialized)
  * 6. Required documentation lanes exist (if specified in init)
  *
@@ -18,6 +20,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { statSync, readFileSync, existsSync } from "node:fs";
+import { hasIntakeReference } from "./intake/traceability.mjs";
+import { ensureCxDir } from "./project-init-shared.mjs";
 
 const args = process.argv.slice(2);
 const quickMode = args.includes("--quick");
@@ -196,6 +200,37 @@ function checkContextHasProgress(contextPath) {
   }
 }
 
+// Surfaces drift: artifacts under intake-fed locations that lack an
+// intake_id / intake: none frontmatter reference. Advisory (warning) because
+// not every artifact necessarily comes from an intake packet — but the absence
+// is a flag for the operator to either stamp the provenance or declare it
+// intake-independent.
+function checkIntakeTraceability(cwd) {
+  const intakeFedDirs = [
+    path.join(cwd, 'docs', 'prd'),
+    path.join(cwd, 'docs', 'research'),
+    path.join(cwd, '.cx', 'knowledge', 'internal'),
+  ];
+  let inspected = 0;
+  for (const dir of intakeFedDirs) {
+    if (!fs.existsSync(dir)) continue;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+      if (entry.name.startsWith('_') || entry.name.toLowerCase() === 'readme.md') continue;
+      const filePath = path.join(dir, entry.name);
+      inspected += 1;
+      if (!hasIntakeReference(filePath)) {
+        warnings.push(
+          `Intake traceability: ${path.relative(cwd, filePath)} lacks intake_id or "intake: none" in frontmatter — stamp via \`construct intake done <id> --output\` or declare intake-independent.`,
+        );
+      }
+    }
+  }
+  return inspected;
+}
+
 function checkDocsSystem(docsPath) {
   if (!fs.existsSync(docsPath)) {
     // docs/ directory doesn't exist, which is fine if project doesn't use docs system
@@ -331,7 +366,25 @@ function main() {
   // Critical checks (fail CI)
   checkExists(path.join(cwd, "README.md"), "README.md", true);
   checkExists(path.join(cwd, "AGENTS.md"), "AGENTS.md", true);
-  checkExists(path.join(cwd, ".cx", "context.md"), ".cx/context.md", true);
+
+  // .cx/context.md invariant. The verifier is the canonical enforcer: if .cx/
+  // exists but context.md does not, the file is reconstituted from the init
+  // template here. This is consistent with construct init (which creates both
+  // together) and absorbs the case where a subsystem creates a .cx/ subdirectory
+  // for operational reasons without going through ensureCxDir. CI starts with
+  // no .cx/ at all (gitignored) so the block is skipped entirely. Staleness
+  // remains critical — a context.md older than 7 days indicates sessions that
+  // are running without keeping the handoff state current, which is the real
+  // bug the gate exists to catch.
+  const cxDir = path.join(cwd, ".cx");
+  const contextMdPath = path.join(cxDir, "context.md");
+  const cxExists = fs.existsSync(cxDir);
+  if (cxExists) {
+    if (!fs.existsSync(contextMdPath)) {
+      ensureCxDir(cwd);
+    }
+    checkFileAge(contextMdPath, 7, ".cx/context.md", true);
+  }
 
   // plan.md is a local working document — gitignored, not committed.
   // Verify it's healthy when present, but don't fail when it's absent.
@@ -339,16 +392,16 @@ function main() {
 
   // Age checks (fail CI if stale)
   if (planExists) checkFileAge(path.join(cwd, "plan.md"), 7, "plan.md", true);
-  checkFileAge(path.join(cwd, ".cx", "context.md"), 7, ".cx/context.md", true);
 
   if (!quickMode) {
     // Detailed checks (warnings only)
     checkReadmeBasicSections(path.join(cwd, "README.md"));
     checkAgentsRequiredSections(path.join(cwd, "AGENTS.md"));
     if (planExists) checkPlanLinkedToIssues(path.join(cwd, "plan.md"));
-    checkContextHasProgress(path.join(cwd, ".cx", "context.md"));
+    if (cxExists && fs.existsSync(contextMdPath)) checkContextHasProgress(contextMdPath);
     checkDocsSystem(path.join(cwd, "docs"));
-    
+    checkIntakeTraceability(cwd);
+
     // Age warning for README.md (30 days)
     checkFileAge(path.join(cwd, "README.md"), 30, "README.md", false);
   }

package/lib/doctor/cli.mjs

@@ -85,6 +85,7 @@ export async function runCli(args) {
       import('./watchers/process-pressure.mjs'),
       import('./watchers/service-health.mjs'),
       import('./watchers/bd-watch.mjs'),
+      import('./watchers/consistency.mjs'),
     ]);
     for (const w of watchers) {
       const r = await w.tick();
@@ -93,7 +94,21 @@ export async function runCli(args) {
     return 0;
   }
 
+  if (sub === 'consistency') {
+    const { runAllChecks } = await import('./watchers/consistency.mjs');
+    const result = await runAllChecks();
+    const blocking = result.findings.filter((f) => f.severity === 'blocking');
+    const warnings = result.findings.filter((f) => f.severity === 'warning');
+
+    for (const p of result.passed) console.log(`  ✓  ${p.category.padEnd(18)} ${p.summary}`);
+    for (const w of warnings) console.log(`  ⚠  ${w.category.padEnd(18)} ${w.summary}`);
+    for (const b of blocking) console.log(`  ✗  ${b.category.padEnd(18)} ${b.summary}`);
+
+    console.log(`\n${result.passed.length} category(s) clean, ${warnings.length} warning(s), ${blocking.length} blocking finding(s)`);
+    return blocking.length > 0 ? 1 : 0;
+  }
+
   console.error(`Unknown doctor subcommand: ${sub}`);
-  console.error('Usage: construct doctor [status|watch|stop|logs|tick]');
+  console.error('Usage: construct doctor [status|watch|stop|logs|tick|consistency]');
   return 2;
 }

package/lib/doctor/index.mjs

@@ -22,9 +22,11 @@ import * as processPressure from './watchers/process-pressure.mjs';
 import * as serviceHealth from './watchers/service-health.mjs';
 import * as bdWatch from './watchers/bd-watch.mjs';
 import * as handoffs from './watchers/handoffs.mjs';
+import * as consistency from './watchers/consistency.mjs';
+import * as mcpProtocol from './watchers/mcp-protocol.mjs';
 
 const STATE_PATH = join(homedir(), '.construct', 'doctor.json');
-const WATCHERS = [disk, cost, processPressure, serviceHealth, bdWatch, handoffs];
+const WATCHERS = [disk, cost, processPressure, serviceHealth, bdWatch, handoffs, consistency, mcpProtocol];
 
 let running = false;
 let timers = [];