@geraldmaron/construct 1.1.0 → 1.2.0

package/lib/oracle/actions.mjs

@@ -0,0 +1,187 @@
+/**
+ * lib/oracle/actions.mjs — Oracle tick executor with bounded-auto policy.
+ *
+ * Auto actions: alignment census spawn, registry validate import, adapters
+ * sync (Construct tool repo only). Approve actions queue to
+ * <project>/.cx/oracle/pending.jsonl. High-severity gaps auto-raise beads
+ * when enabled. Denied actions are skipped.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { collectReadModel, enrichReadModel } from './read-model.mjs';
+import { synthesizeVerdict } from './synthesize.mjs';
+import { classifyAction, autoRaiseEnabled, autoRaiseEnabledForGap } from './policy.mjs';
+import { isConstructPackageRepo } from '../host-disposition.mjs';
+import { syncProjectAdapters } from '../adapters-sync.mjs';
+import { writeVerdict } from './verdicts.mjs';
+import { raiseIssuesForGaps } from './issues.mjs';
+import { maybeWriteHighSeverityRouting } from './dispatch.mjs';
+import { executeApprovedAction } from './execute.mjs';
+import { signOffMetadata } from './routing.mjs';
+
+function pendingPath(projectDir) {
+  return path.join(projectDir, '.cx', 'oracle', 'pending.jsonl');
+}
+
+function ensureOracleDir(projectDir) {
+  const dir = path.join(projectDir, '.cx', 'oracle');
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function appendPending(projectDir, record) {
+  ensureOracleDir(projectDir);
+  const line = JSON.stringify({ ...record, queuedAt: new Date().toISOString() }) + '\n';
+  fs.appendFileSync(pendingPath(projectDir), line, 'utf8');
+}
+
+export function listPending(projectDir) {
+  const file = pendingPath(projectDir);
+  if (!fs.existsSync(file)) return [];
+  return fs.readFileSync(file, 'utf8')
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => { try { return JSON.parse(line); } catch { return null; } })
+    .filter(Boolean);
+}
+
+function rewritePending(projectDir, pending) {
+  const file = pendingPath(projectDir);
+  fs.writeFileSync(file, pending.map((p) => JSON.stringify(p)).join('\n') + (pending.length ? '\n' : ''), 'utf8');
+}
+
+export async function approvePending(projectDir, id, { execute = true, rootDir, homeDir, dryRun = false } = {}) {
+  const pending = listPending(projectDir);
+  const match = pending.find((p) => p.id === id);
+  if (!match) return { ok: false, reason: 'not-found' };
+  if (match.status === 'approved' && match.executedAt) {
+    return { ok: true, already: true, action: match };
+  }
+  match.status = 'approved';
+  match.approvedAt = new Date().toISOString();
+  match.signOff = match.signOff ?? signOffMetadata({ id: match.kind }, projectDir);
+
+  let executionResult = null;
+  if (execute) {
+    try {
+      executionResult = await executeApprovedAction(match, {
+        rootDir: rootDir ?? defaultRootDir(),
+        projectDir,
+        homeDir,
+        dryRun,
+      });
+      match.executedAt = new Date().toISOString();
+      match.executionResult = executionResult;
+      if (executionResult?.gateway?.bdIssueId) match.beadId = executionResult.gateway.bdIssueId;
+    } catch (err) {
+      match.executionResult = { ok: false, error: err?.message || String(err) };
+    }
+  }
+
+  rewritePending(projectDir, pending);
+  return { ok: true, action: match, executionResult };
+}
+
+async function executeAutoAction(kind, { rootDir, projectDir, dryRun }) {
+  if (dryRun) return { kind, dryRun: true, ok: true };
+
+  switch (kind) {
+    case 'census-run': {
+      const script = path.join(rootDir, 'scripts', 'alignment', 'census.mjs');
+      if (!fs.existsSync(script)) return { kind, ok: false, error: 'census script missing' };
+      const result = spawnSync(process.execPath, [script], { cwd: rootDir, encoding: 'utf8' });
+      return {
+        kind,
+        ok: result.status === 0,
+        exitCode: result.status,
+        stderr: (result.stderr || '').slice(0, 500),
+      };
+    }
+    case 'registry-validate': {
+      const { validateCapabilityRegistry } = await import('../registry/validate.mjs');
+      const report = validateCapabilityRegistry({ rootDir });
+      return { kind, ok: report.valid, errors: report.errors?.length ?? 0, warnings: report.warnings?.length ?? 0 };
+    }
+    case 'adapters-sync': {
+      if (!isConstructPackageRepo(projectDir)) {
+        return { kind, ok: true, skipped: true, reason: 'not-tool-repo' };
+      }
+      const result = syncProjectAdapters({ projectRoot: projectDir, packageRoot: rootDir, log: () => {} });
+      return { kind, ok: !!result.synced, hosts: result.hosts ?? [] };
+    }
+    default:
+      return { kind, ok: false, error: 'unknown-auto-action' };
+  }
+}
+
+/**
+ * Run one Oracle tick: collect signals, synthesize verdict, execute auto
+ * actions, queue approve actions, raise beads for high gaps.
+ */
+export async function runOracleTick({ rootDir, projectDir, homeDir, dryRun = false } = {}) {
+  let readModel = collectReadModel({ rootDir, projectDir, homeDir });
+  readModel = await enrichReadModel(readModel);
+  const synthesis = synthesizeVerdict(readModel);
+
+  const executed = [];
+  const queued = [];
+  const skipped = [];
+  let beadsRaised = [];
+
+  if (autoRaiseEnabled() && synthesis.gaps.some((g) => autoRaiseEnabledForGap(g))) {
+    beadsRaised = await raiseIssuesForGaps({ projectDir, gaps: synthesis.gaps, dryRun });
+  }
+
+  for (const rec of synthesis.recommendedActions) {
+    const classification = classifyAction(rec.kind);
+    if (classification === 'deny') {
+      skipped.push({ ...rec, classification });
+      continue;
+    }
+    if (classification === 'auto') {
+      const result = await executeAutoAction(rec.kind, { rootDir, projectDir, dryRun });
+      executed.push({ ...rec, classification, result });
+      continue;
+    }
+    const id = `oracle-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const pending = {
+      id,
+      kind: rec.kind,
+      summary: rec.summary,
+      classification,
+      status: 'pending',
+      signOff: rec.signOff ?? signOffMetadata({ id: rec.kind }, projectDir),
+      context: { ...rec },
+    };
+    if (!dryRun) appendPending(projectDir, pending);
+    queued.push(pending);
+  }
+
+  const tick = {
+    at: new Date().toISOString(),
+    dryRun,
+    verdict: synthesis.verdict,
+    gaps: synthesis.gaps,
+    executed,
+    queued,
+    skipped,
+    beadsRaised,
+  };
+
+  if (!dryRun) {
+    writeVerdict(projectDir, tick, { beadsRaised, orgGraph: readModel.orgGraph });
+    maybeWriteHighSeverityRouting({ projectDir, tick, synthesis, readModel });
+  }
+
+  return { readModel, ...synthesis, tick };
+}
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+
+export function defaultRootDir() {
+  return path.resolve(MODULE_DIR, '../..');
+}

package/lib/oracle/artifact-gate.mjs

@@ -0,0 +1,99 @@
+/**
+ * lib/oracle/artifact-gate.mjs — Oracle read-model signals for typed artifact gates.
+ *
+ * Surfaces manifest audit drift, release-gate bypass markers, and high-risk
+ * artifacts missing required reviewers in the agent log.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { auditSpecialists } from '../audit-specialists.mjs';
+import { inferArtifactTypeFromPath, isArtifactGatePath } from '../artifact-type-from-path.mjs';
+import {
+  missingRequiredReviewers,
+  parseReleaseGateFrontmatter,
+} from '../artifact-reviewers.mjs';
+import { isConstructPackageRepo } from '../host-disposition.mjs';
+
+function walkMarkdown(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walkMarkdown(full, out);
+    else if (entry.name.endsWith('.md')) out.push(full);
+  }
+  return out;
+}
+
+function collectBypassArtifacts(projectDir) {
+  const roots = [
+    path.join(projectDir, 'docs'),
+    path.join(projectDir, '.cx', 'research'),
+  ];
+  const bypassed = [];
+  for (const root of roots) {
+    for (const file of walkMarkdown(root)) {
+      const rel = path.relative(projectDir, file).replace(/\\/g, '/');
+      if (!isArtifactGatePath(rel)) continue;
+      const { bypass, reason } = parseReleaseGateFrontmatter(file);
+      if (!bypass) continue;
+      bypassed.push({
+        path: rel,
+        type: inferArtifactTypeFromPath(file, { rootDir: projectDir }),
+        reason: reason || null,
+      });
+    }
+  }
+  return bypassed;
+}
+
+function collectReviewerGaps(projectDir) {
+  const roots = [
+    path.join(projectDir, 'docs', 'prd'),
+    path.join(projectDir, 'docs', 'adr'),
+    path.join(projectDir, 'docs', 'rfc'),
+  ];
+  const gaps = [];
+  for (const root of roots) {
+    if (!fs.existsSync(root)) continue;
+    for (const file of walkMarkdown(root)) {
+      const rel = path.relative(projectDir, file).replace(/\\/g, '/');
+      const type = inferArtifactTypeFromPath(file, { rootDir: projectDir });
+      if (!type) continue;
+      const missing = missingRequiredReviewers({ filePath: file, cwd: projectDir });
+      if (missing.length > 0) {
+        gaps.push({ path: rel, type, missingReviewers: missing });
+      }
+    }
+  }
+  return gaps.slice(0, 20);
+}
+
+export function collectArtifactGateSignals({ rootDir, projectDir }) {
+  const bypassed = collectBypassArtifacts(projectDir);
+  const reviewerGaps = collectReviewerGaps(projectDir);
+
+  let specialistAudit = { present: false, pass: true, crossCheckCount: 0 };
+  if (isConstructPackageRepo(projectDir)) {
+    try {
+      const audit = auditSpecialists({ rootDir, silent: true });
+      specialistAudit = {
+        present: true,
+        pass: audit.pass,
+        crossCheckCount: audit.crossCheckIssues?.length ?? 0,
+        crossCheckIssues: (audit.crossCheckIssues ?? []).slice(0, 5),
+      };
+    } catch {
+      specialistAudit = { present: true, pass: false, crossCheckCount: -1 };
+    }
+  }
+
+  return {
+    bypassed,
+    bypassCount: bypassed.length,
+    reviewerGaps,
+    reviewerGapCount: reviewerGaps.length,
+    specialistAudit,
+  };
+}

package/lib/oracle/cli.mjs

@@ -0,0 +1,204 @@
+/**
+ * lib/oracle/cli.mjs — CLI handlers for `construct oracle <subcommand>`.
+ *
+ * Subcommands: start, status, review, pending, approve, gaps, reconcile.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { readHeartbeat } from '../daemons/contract.mjs';
+import {
+  buildOracleDaemon,
+  heartbeatPath,
+  readLastTick,
+  KILLSWITCH_ENV,
+} from './index.mjs';
+import { runOracleTick, listPending, approvePending, defaultRootDir } from './actions.mjs';
+import { collectOracleGaps, formatOracleGapsReport } from './gaps.mjs';
+import { reconcileOracleHygieneBeads } from './reconcile.mjs';
+
+const MODULE_FILE = fileURLToPath(import.meta.url);
+
+function runtimeDir(homeDir) {
+  return path.join(homeDir, '.cx', 'runtime', 'oracle');
+}
+
+async function cmdStart(args, { rootDir, projectDir, homeDir }) {
+  const hb = heartbeatPath(homeDir);
+  const live = readHeartbeat(hb);
+  if (live) {
+    process.stdout.write(`oracle daemon already running (pid ${live.pid})\n`);
+    return 0;
+  }
+
+  if (process.env[KILLSWITCH_ENV] === 'off' || process.env[KILLSWITCH_ENV] === '0') {
+    process.stderr.write(`oracle daemon disabled (${KILLSWITCH_ENV}=off)\n`);
+    return 1;
+  }
+
+  const foreground = args.includes('--foreground') || args.includes('-f');
+  if (foreground) {
+    const daemon = buildOracleDaemon({ rootDir, projectDir, homeDir });
+    const result = await daemon.run();
+    process.stdout.write(`oracle daemon stopped: ${result.reason}\n`);
+    return 0;
+  }
+
+  const entry = path.join(path.dirname(MODULE_FILE), 'daemon-entry.mjs');
+  const logDir = runtimeDir(homeDir);
+  fs.mkdirSync(logDir, { recursive: true });
+  const logFile = path.join(logDir, 'oracle-daemon.log');
+  const fd = fs.openSync(logFile, 'a');
+
+  const child = spawn(process.execPath, [entry], {
+    detached: true,
+    stdio: ['ignore', fd, fd],
+    env: {
+      ...process.env,
+      CONSTRUCT_ORACLE_ROOT: rootDir,
+      CONSTRUCT_ORACLE_PROJECT: projectDir,
+    },
+    cwd: projectDir,
+  });
+  child.unref();
+  process.stdout.write(`oracle daemon started (pid ${child.pid})\n`);
+  return 0;
+}
+
+function cmdStatus(_args, { homeDir }) {
+  const hb = readHeartbeat(heartbeatPath(homeDir));
+  const last = readLastTick(homeDir);
+  const payload = {
+    running: !!hb,
+    heartbeat: hb,
+    lastTick: last,
+    killswitch: process.env[KILLSWITCH_ENV] === 'off' || process.env[KILLSWITCH_ENV] === '0',
+  };
+  process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+  return 0;
+}
+
+async function cmdReview(args, { rootDir, projectDir, homeDir }) {
+  const dryRun = args.includes('--dry-run');
+  const json = args.includes('--json');
+  const result = await runOracleTick({ rootDir, projectDir, homeDir, dryRun });
+  if (json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    return 0;
+  }
+  process.stdout.write(`Oracle verdict: ${result.verdict}\n`);
+  if (result.gaps.length) {
+    process.stdout.write(`Gaps (${result.gaps.length}):\n`);
+    for (const g of result.gaps) {
+      process.stdout.write(`  [${g.severity}] ${g.id}: ${g.detail}\n`);
+    }
+  }
+  if (result.tick.executed.length) {
+    process.stdout.write(`Auto-executed (${result.tick.executed.length}):\n`);
+    for (const e of result.tick.executed) {
+      process.stdout.write(`  ${e.kind}: ${e.result?.ok ? 'ok' : 'failed'}\n`);
+    }
+  }
+  if (result.tick.queued.length) {
+    process.stdout.write(`Queued for approval (${result.tick.queued.length}):\n`);
+    for (const q of result.tick.queued) {
+      process.stdout.write(`  ${q.id} ${q.kind}: ${q.summary}\n`);
+    }
+  }
+  return 0;
+}
+
+function cmdPending(_args, { projectDir }) {
+  const pending = listPending(projectDir).filter((p) => p.status !== 'approved');
+  process.stdout.write(JSON.stringify(pending, null, 2) + '\n');
+  return 0;
+}
+
+function cmdApprove(args, { projectDir, rootDir, homeDir }) {
+  const id = args.find((a) => !a.startsWith('-'));
+  if (!id) {
+    process.stderr.write('Usage: construct oracle approve <id> [--no-execute]\n');
+    return 1;
+  }
+  const noExecute = args.includes('--no-execute');
+  return approvePending(projectDir, id, {
+    execute: !noExecute,
+    rootDir,
+    homeDir,
+  }).then((result) => {
+    if (!result.ok) {
+      process.stderr.write(`approve failed: ${result.reason}\n`);
+      return 1;
+    }
+    process.stdout.write(JSON.stringify(result.action, null, 2) + '\n');
+    return 0;
+  });
+}
+
+function cmdGaps(args, { projectDir }) {
+  const json = args.includes('--json');
+  const data = collectOracleGaps(projectDir);
+  if (json) {
+    process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+    return 0;
+  }
+  process.stdout.write(formatOracleGapsReport(data));
+  return 0;
+}
+
+async function cmdReconcile(args, { projectDir }) {
+  const dryRun = args.includes('--dry-run');
+  const json = args.includes('--json');
+  const result = await reconcileOracleHygieneBeads({ projectDir, dryRun });
+  if (json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    return 0;
+  }
+  process.stdout.write(`Oracle reconcile${dryRun ? ' (dry-run)' : ''}: found ${result.found} hygiene beads\n`);
+  if (Object.keys(result.kept).length) {
+    process.stdout.write(`Keeping newest per gap: ${JSON.stringify(result.kept)}\n`);
+  }
+  process.stdout.write(`Planned close: ${result.plannedClose.length}\n`);
+  if (!dryRun) process.stdout.write(`Closed: ${result.closed.length}\n`);
+  if (result.raisedPruned) process.stdout.write(`Pruned raised-issues rows: ${result.raisedPruned}\n`);
+  if (result.contractViolations?.superseded) {
+    process.stdout.write(`Superseded ${result.contractViolations.recentCount} bare-goal contract violation(s)\n`);
+  } else if (result.contractViolations?.wouldSupersede) {
+    process.stdout.write(`Would supersede ${result.contractViolations.recentCount} bare-goal contract violation(s)\n`);
+  }
+  return 0;
+}
+
+/**
+ * Entry point for bin/construct.
+ */
+export async function runOracleCli(args, opts = {}) {
+  const sub = args[0];
+  const subArgs = args.slice(1);
+  const homeDir = opts.homeDir ?? os.homedir();
+  const rootDir = opts.rootDir ?? defaultRootDir();
+  const projectDir = opts.projectDir ?? process.cwd();
+
+  switch (sub) {
+    case 'start': return cmdStart(subArgs, { rootDir, projectDir, homeDir });
+    case 'status': return cmdStatus(subArgs, { homeDir });
+    case 'review': return cmdReview(subArgs, { rootDir, projectDir, homeDir });
+    case 'pending': return cmdPending(subArgs, { projectDir });
+    case 'approve': return cmdApprove(subArgs, { projectDir, rootDir, homeDir });
+    case 'gaps': return cmdGaps(subArgs, { projectDir });
+    case 'reconcile': return cmdReconcile(subArgs, { projectDir });
+    default:
+      process.stderr.write(
+        'Usage: construct oracle <start|status|review|pending|approve|gaps|reconcile> [--json] [--dry-run] [--foreground] [--no-execute]\n',
+      );
+      if (sub && sub !== '--help' && sub !== '-h') {
+        process.stderr.write(`Unknown subcommand: ${sub}\n`);
+        return 1;
+      }
+      return sub === '--help' || sub === '-h' ? 0 : 1;
+  }
+}

package/lib/oracle/daemon-entry.mjs

@@ -0,0 +1,14 @@
+/**
+ * lib/oracle/daemon-entry.mjs — detached entrypoint for `construct oracle start`.
+ *
+ * Spawns the Oracle daemon in the background. Reads root/project overrides
+ * from CONSTRUCT_ORACLE_ROOT and CONSTRUCT_ORACLE_PROJECT.
+ */
+
+import { runOracleDaemon } from './index.mjs';
+import { defaultRootDir } from './actions.mjs';
+
+const rootDir = process.env.CONSTRUCT_ORACLE_ROOT || defaultRootDir();
+const projectDir = process.env.CONSTRUCT_ORACLE_PROJECT || process.cwd();
+
+await runOracleDaemon({ rootDir, projectDir });

package/lib/oracle/dispatch.mjs

@@ -0,0 +1,81 @@
+/**
+ * lib/oracle/dispatch.mjs — cx-oracle routing artifacts (deterministic, LLM-free).
+ *
+ * Writes audit markdown under .cx/oracle/routing/ for approve-gated dispatch.
+ * Optional high-severity auto-artifact on tick when gaps are load-bearing.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { routeGap, routeAction } from './routing.mjs';
+
+export function routingDir(projectDir) {
+  return path.join(projectDir, '.cx', 'oracle', 'routing');
+}
+
+/**
+ * Build deterministic routing markdown from synthesis packet.
+ */
+export function buildRoutingArtifact({ synthesis, readModel, tickId, route }) {
+  const lines = [
+    `# ORACLE ROUTING — ${tickId}`,
+    '',
+    `VERDICT: ${synthesis.verdict ?? 'unknown'}`,
+    '',
+    'GAPS:',
+  ];
+
+  for (const gap of synthesis.gaps ?? []) {
+    const r = routeGap(gap);
+    lines.push(`  [${gap.severity}] ${gap.id} — ${gap.detail}`);
+    lines.push(`    signal: ${gap.signal ?? 'unknown'}`);
+    lines.push(`    route: ${r.primary}${r.secondary ? ` (secondary: ${r.secondary})` : ''}`);
+    if (r.gateType) lines.push(`    gate: ${r.gateType}`);
+  }
+
+  if (!synthesis.gaps?.length) lines.push('  (none)');
+
+  lines.push('', 'RECOMMENDED ACTIONS:');
+  for (const action of synthesis.recommendedActions ?? []) {
+    const r = routeAction(action.kind);
+    lines.push(`  ${action.kind}: ${action.summary}`);
+    lines.push(`    route: ${r.primary} · gate: ${r.gateType ?? 'none'}`);
+  }
+  if (!synthesis.recommendedActions?.length) lines.push('  (none)');
+
+  if (readModel?.collectedAt) {
+    lines.push('', `Read model collected: ${readModel.collectedAt}`);
+  }
+  if (route?.primary) {
+    lines.push('', `DISPATCH TARGET: ${route.primary}`);
+  }
+
+  lines.push('', 'BLOCKED:', '  none (deterministic routing artifact — LLM dispatch is approve-gated)');
+  return lines.join('\n');
+}
+
+/**
+ * @returns {string} artifact path relative to project root
+ */
+export function writeRoutingArtifact({ projectDir, tickId, synthesis, readModel, route }) {
+  const dir = routingDir(projectDir);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const fileName = `${tickId.replace(/[^a-zA-Z0-9._-]/g, '_')}.md`;
+  const file = path.join(dir, fileName);
+  const content = buildRoutingArtifact({ synthesis, readModel, tickId, route });
+  fs.writeFileSync(file, content, 'utf8');
+  return path.relative(projectDir, file);
+}
+
+/**
+ * Write routing artifact for high-severity tick when any HIGH gap exists.
+ */
+export function maybeWriteHighSeverityRouting({ projectDir, tick, synthesis, readModel }) {
+  const hasHigh = (synthesis.gaps ?? []).some((g) => g.severity === 'high');
+  if (!hasHigh) return null;
+  const tickId = tick.at ?? new Date().toISOString();
+  const primaryGap = synthesis.gaps.find((g) => g.severity === 'high');
+  const route = routeGap(primaryGap);
+  return writeRoutingArtifact({ projectDir, tickId, synthesis, readModel, route });
+}