@geraldmaron/construct 1.4.1 → 1.5.0

package/lib/oracle/heartbeat.mjs

@@ -0,0 +1,53 @@
+/**
+ * lib/oracle/heartbeat.mjs — oracle producer liveness from the last-tick record.
+ *
+ * The oracle daemon records last-tick.json when a tick completes and idles itself
+ * out after a few no-work ticks, so a stale tick on its own is not death — it is a
+ * dead-producer signal only when oracle work is actually waiting (pending approvals
+ * or unaddressed gaps). Consumers therefore pair heartbeatFreshness with a pending
+ * count; this module owns only the age check. It is deliberately distinct from
+ * verdictFreshness in lib/intake/session-prelude.mjs, which ages the verdict's own
+ * `at` (is the answer current) rather than the producer's tick `at` (is anything
+ * still generating answers). formatAge is shared with the verdict path.
+ */
+
+import { readLastTick } from './index.mjs';
+
+// Six missed 5-minute intervals clears the daemon's idle-shutdown window before a
+// stale tick is treated as a stalled producer, so a briefly-quiet daemon is never
+// mislabelled dead.
+export const ORACLE_TICK_INTERVAL_MS = 5 * 60_000;
+export const HEARTBEAT_STALE_MS = ORACLE_TICK_INTERVAL_MS * 6;
+
+export function formatAge(ageMs) {
+  if (!Number.isFinite(ageMs)) return 'unknown';
+  const hours = Math.floor(ageMs / (60 * 60 * 1000));
+  if (hours < 1) return '<1h';
+  if (hours < 24) return `${hours}h`;
+  return `${Math.floor(hours / 24)}d`;
+}
+
+// Missing or unparseable `at` resolves to Infinity — stale, never fresh — so an
+// absent tick record reads as a stalled producer rather than a healthy one.
+
+export function heartbeatFreshness(lastTick, now = Date.now()) {
+  const at = lastTick?.at;
+  const parsed = at ? Date.parse(at) : NaN;
+  const ageMs = Number.isFinite(parsed) ? now - parsed : Infinity;
+  return {
+    ageMs,
+    stale: !Number.isFinite(ageMs) || ageMs > HEARTBEAT_STALE_MS,
+    asOf: Number.isFinite(parsed) ? new Date(parsed).toISOString() : null,
+  };
+}
+
+// Honors the oracle off-switch so a deliberately disabled daemon is never flagged.
+
+export function readHeartbeatStatus({ homeDir, env = process.env } = {}) {
+  if (env?.CONSTRUCT_ORACLE === 'off' || env?.CONSTRUCT_ORACLE === '0') {
+    return { enabled: false, lastTick: null, ageMs: null, stale: false, asOf: null };
+  }
+  const lastTick = readLastTick(homeDir);
+  const { ageMs, stale, asOf } = heartbeatFreshness(lastTick);
+  return { enabled: true, lastTick, ageMs, stale, asOf };
+}

package/lib/oracle/read-model.mjs

@@ -22,7 +22,7 @@ import { collectArtifactGateSignals } from './artifact-gate.mjs';
 import { loadGraph, nodesByType, dependentsOf } from '../graph/store.mjs';
 import { hashFiles } from '../graph/build-from-registry.mjs';
 import { GRAPH_SEED_FILES } from '../graph/staleness.mjs';
-import { readViolationSupersedeCutoff } from '../contracts/violation-log.mjs';
+import { recentViolations } from '../contracts/violation-log.mjs';
 import { doctorRoot } from '../config/xdg.mjs';
 
 const RECENT_MS = 24 * 60 * 60 * 1000;
@@ -109,14 +109,12 @@ function collectOutcomesSummary(projectDir) {
 
 function collectContractViolations(projectDir) {
   const file = path.join(projectDir, '.cx', 'contract-violations.jsonl');
-  const since = Date.now() - RECENT_MS;
-  const supersedeCutoff = readViolationSupersedeCutoff(projectDir);
-  const recent = readRecentJsonl(file, { since, limit: VIOLATION_LIMIT })
-    .filter((row) => {
-      if (!row?.ts) return false;
-      if (supersedeCutoff != null && new Date(row.ts).getTime() <= supersedeCutoff) return false;
-      return true;
-    });
+  const recent = recentViolations({
+    windowMs: RECENT_MS,
+    repoRoot: projectDir,
+    excludeDevNoise: true,
+    limit: VIOLATION_LIMIT,
+  });
   return {
     present: fs.existsSync(file),
     recentCount: recent.length,
@@ -243,7 +241,57 @@ function collectStructureSprawl(projectDir) {
 // edge), and freshness (a capability whose realizing files changed after its
 // lastValidated stamp). Never throws; an absent graph yields present:false.
 
-function collectDependencyGraph(rootDir, projectDir) {
+// Freshness needs content identity, not mtime: any checkout, rebase, or touch
+// rewrites file mtimes repo-wide without changing a single byte, so a pure
+// mtime > stamp comparison flags every capability on every fresh clone. A
+// file only "changed since lastValidated" if its working-tree bytes differ
+// from HEAD (dirty edit) or a commit touching it landed after the stamp
+// (`git log --since`). Both checks are batched into one spawnSync each so
+// the cost stays O(1) per capability rather than O(realizers).
+
+function gitDirtyFiles(rootDir) {
+  try {
+    const res = spawnSync('git', ['diff', '--name-only', 'HEAD'], { cwd: rootDir, encoding: 'utf8' });
+    if (res.status !== 0) return null;
+    return new Set(res.stdout.split('\n').map((l) => l.trim()).filter(Boolean));
+  } catch {
+    return null;
+  }
+}
+
+function gitFilesChangedSince(rootDir, sinceIso, rels) {
+  if (rels.length === 0) return new Set();
+  try {
+    const res = spawnSync(
+      'git',
+      ['log', `--since=${sinceIso}`, '--name-only', '--pretty=format:', '--', ...rels],
+      { cwd: rootDir, encoding: 'utf8' },
+    );
+    if (res.status !== 0) return null;
+    return new Set(res.stdout.split('\n').map((l) => l.trim()).filter(Boolean));
+  } catch {
+    return null;
+  }
+}
+
+// Validation-grade freshness must not reuse the advisory `realizes` closure:
+// build-import-graph.mjs deliberately widens that edge set for impact tracing
+// (a broad edge only widens advisory reach, which is safe there). Reused
+// here it would treat all 300+ files transitively reachable from a
+// capability's tests as realizers, guaranteeing false positives. The
+// freshness gate instead only trusts direct, declaration-sourced realizes
+// edges (source: 'registry') — the curated implFiles list a capability
+// actually declares — leaving the wide closure untouched for `construct
+// trace`/`impact`.
+
+function directRealizers(graph, capId) {
+  const edges = graph.in.get(capId) || [];
+  return edges
+    .filter((e) => e.rel === 'realizes' && (e.sources || []).includes('registry'))
+    .map((e) => e.from.slice('file:'.length));
+}
+
+export function collectDependencyGraph(rootDir, projectDir) {
   const graph = loadGraph(projectDir);
   if (!graph.exists) {
     return { present: false, applicable: isConstructPackageRepo(projectDir) };
@@ -271,18 +319,26 @@ function collectDependencyGraph(rootDir, projectDir) {
   const orphanFileCount = nodesByType(graph, 'file')
     .filter((f) => (graph.out.get(f.id) || []).every((e) => e.rel !== 'realizes')).length;
 
+  const dirtyFiles = gitDirtyFiles(rootDir);
   const untested = [];
   for (const cap of nodesByType(graph, 'capability')) {
     const lastValidated = cap.attrs?.lastValidated;
     if (!lastValidated) continue;
     const stamp = Date.parse(lastValidated);
     if (!Number.isFinite(stamp)) continue;
-    const realizers = dependentsOf(graph, cap.id, 'realizes').map((id) => id.slice('file:'.length));
+    const realizers = directRealizers(graph, cap.id);
+    if (realizers.length === 0) continue;
+    const committedChanged = gitFilesChangedSince(rootDir, lastValidated, realizers);
     let changed = 0;
     for (const rel of realizers) {
       try {
-        if (fs.statSync(path.join(rootDir, rel)).mtimeMs > stamp) changed++;
-      } catch { /* file gone — coverage handles it */ }
+        fs.statSync(path.join(rootDir, rel));
+      } catch {
+        continue;
+      }
+      const dirty = dirtyFiles?.has(rel) ?? false;
+      const committed = committedChanged?.has(rel) ?? false;
+      if (dirty || committed) changed++;
     }
     if (changed > 0) untested.push({ capability: cap.id.slice('capability:'.length), changedFiles: changed, lastValidated });
   }

package/lib/oracle/reconcile.mjs

@@ -9,7 +9,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { runBd } from '../beads-client.mjs';
-import { markContractViolationsSuperseded, recentViolations } from '../contracts/violation-log.mjs';
+import { isDevSessionContractNoise, markContractViolationsSuperseded, recentViolations } from '../contracts/violation-log.mjs';
 import { VERDICT_ONLY_GAP_IDS } from './policy.mjs';
 import { oracleBeadTitlePrefix } from './issues.mjs';
 
@@ -91,55 +91,12 @@ function pruneRaisedIssues(projectDir, { dryRun = false } = {}) {
   return { pruned };
 }
 
-const BARE_GOAL_FIELD_LABELS = ['intent', 'workCategory', 'riskFlags', 'acceptanceCriteria'];
-
-const RESEARCHER_PROBE_MISSING = [
-  'artifact missing required field: question',
-  'artifact missing required field: method',
-  'artifact missing required field: sources',
-  'artifact missing required field: findings',
-  'artifact missing required field: confidence',
-];
-
-const A11Y_PROBE_MISSING = [
-  'artifact missing required field: findings',
-  'artifact missing required field: wcagCriterion',
-  'artifact missing required field: userImpact',
-];
-
-function missingBareGoalConstructFields(missing) {
-  if (!Array.isArray(missing) || missing.length !== BARE_GOAL_FIELD_LABELS.length) return false;
-  return BARE_GOAL_FIELD_LABELS.every((field) =>
-    missing.some((entry) => String(entry).includes(field)),
-  );
-}
-
-function isBareGoalConstructViolation(row) {
-  if (row?.contractId !== 'construct-to-orchestrator') return false;
-  if (!missingBareGoalConstructFields(row.missing)) return false;
-  const keys = row.packet_keys ?? row.packetKeys;
-  return Array.isArray(keys) && keys.length === 1 && keys[0] === 'goal';
-}
-
-function isEmptyProbeViolation(row, contractId, expectedMissing) {
-  if (row?.contractId !== contractId) return false;
-  const keys = row.packet_keys ?? row.packetKeys;
-  if (!Array.isArray(keys) || keys.length !== 0) return false;
-  return JSON.stringify(row.missing) === JSON.stringify(expectedMissing);
-}
-
-function isDevSessionContractNoise(row) {
-  return isBareGoalConstructViolation(row)
-    || isEmptyProbeViolation(row, 'researcher-to-architect', RESEARCHER_PROBE_MISSING)
-    || isEmptyProbeViolation(row, 'accessibility-to-qa', A11Y_PROBE_MISSING);
-}
-
 /**
  * @param {string} projectDir
  * @returns {{ shouldSupersede: boolean, recentCount: number, reason: string }}
  */
-export function planContractViolationSupersede(projectDir) {
-  const recent = recentViolations({ repoRoot: projectDir });
+export function planContractViolationSupersede(projectDir, { now = Date.now() } = {}) {
+  const recent = recentViolations({ repoRoot: projectDir, now });
   if (!recent.length) {
     return { shouldSupersede: false, recentCount: 0, reason: 'no recent contract violations' };
   }

package/lib/oracle/routing.mjs

@@ -1,54 +1,60 @@
 /**
  * lib/oracle/routing.mjs — deterministic gap → specialist routing table.
  *
- * Mirrors cx-oracle.md routing without LLM involvement. Issue raising,
- * approve execution, and routing artifact generation consume these mappings.
+ * Mirrors skills/operating/fleet-health-routing.md (the fleet-health duty
+ * cx-oracle's retirement folded into cx-orchestrator, construct-rf26.11)
+ * without LLM involvement. Issue raising, approve execution, and routing
+ * artifact generation consume these mappings. Specialist ids reflect the
+ * post-consolidation 12-role roster; team-governance signals route to
+ * cx-operations (owns dependency/ownership mapping) rather than the retired
+ * cx-rd-lead.
  */
 
 const GAP_ROUTES = {
-  'parity-drift': { primary: 'cx-platform-engineer', secondary: 'cx-docs-keeper' },
+  'parity-drift': { primary: 'cx-engineer', secondary: 'cx-operations' },
   'contract-violations': { primary: 'cx-reviewer', secondary: 'cx-engineer' },
-  'doctor-escalation': { primary: 'cx-sre', secondary: 'cx-operations' },
-  'outcomes-degradation': { primary: 'cx-trace-reviewer', secondary: null },
-  'census-stale': { primary: 'cx-architect', secondary: 'cx-docs-keeper' },
-  'alignment-regression': { primary: 'cx-architect', secondary: 'cx-docs-keeper' },
-  'true-skill-orphan': { primary: 'cx-architect', secondary: 'cx-docs-keeper' },
-  'observations-empty': { primary: 'cx-explorer', secondary: 'cx-data-engineer' },
+  'doctor-escalation': { primary: 'cx-operations', secondary: 'cx-operations' },
+  'outcomes-degradation': { primary: 'cx-reviewer', secondary: null },
+  'census-stale': { primary: 'cx-architect', secondary: 'cx-operations' },
+  'alignment-regression': { primary: 'cx-architect', secondary: 'cx-operations' },
+  'true-skill-orphan': { primary: 'cx-architect', secondary: 'cx-operations' },
+  'observations-empty': { primary: 'cx-researcher', secondary: 'cx-engineer' },
   'beads-hygiene': { primary: 'cx-operations', secondary: null },
-  'hook-failures': { primary: 'cx-sre', secondary: null },
-  'registry-warn': { primary: 'cx-platform-engineer', secondary: null },
-  'consistency-drift': { primary: 'cx-platform-engineer', secondary: null },
-  'propagation-stale': { primary: 'cx-platform-engineer', secondary: 'cx-docs-keeper' },
+  'hook-failures': { primary: 'cx-operations', secondary: null },
+  'registry-warn': { primary: 'cx-engineer', secondary: null },
+  'consistency-drift': { primary: 'cx-engineer', secondary: null },
+  'propagation-stale': { primary: 'cx-engineer', secondary: 'cx-operations' },
   'policy-coverage-gap': { primary: 'cx-architect', secondary: null },
   'workflow-misaligned': { primary: 'cx-product-manager', secondary: null },
-  'legal-review-pending': { primary: 'cx-legal-compliance', secondary: null },
-  'capability-unvalidated': { primary: 'cx-platform-engineer', secondary: null },
+  'legal-review-pending': { primary: 'cx-security', secondary: null },
+  'capability-unvalidated': { primary: 'cx-engineer', secondary: null },
   'dead-code-regression': { primary: 'cx-architect', secondary: null },
   'structure-sprawl': { primary: 'cx-architect', secondary: null },
   'init-duplicate-lanes': { primary: 'cx-architect', secondary: null },
-  'outcomes-missing': { primary: 'cx-data-engineer', secondary: null },
-  'repo-layout-legacy': { primary: 'cx-platform-engineer', secondary: 'cx-architect' },
-  'specialist-audit-drift': { primary: 'cx-architect', secondary: 'cx-docs-keeper' },
-  'artifact-gate-bypass': { primary: 'cx-reviewer', secondary: 'cx-docs-keeper' },
+  'outcomes-missing': { primary: 'cx-engineer', secondary: null },
+  'repo-layout-legacy': { primary: 'cx-engineer', secondary: 'cx-architect' },
+  'specialist-audit-drift': { primary: 'cx-architect', secondary: 'cx-operations' },
+  'artifact-gate-bypass': { primary: 'cx-reviewer', secondary: 'cx-operations' },
   'artifact-reviewer-gap': { primary: 'cx-reviewer', secondary: null },
-  'dependency-graph-stale': { primary: 'cx-platform-engineer', secondary: null },
+  'dependency-graph-stale': { primary: 'cx-engineer', secondary: null },
   'matrix-coverage-gap': { primary: 'cx-architect', secondary: 'cx-qa' },
   'impact-untested': { primary: 'cx-qa', secondary: 'cx-engineer' },
-  // Team governance signals — route to rd-lead for strategic resolution
-  'team-understaffed': { primary: 'cx-rd-lead', secondary: 'cx-orchestrator' },
-  'escalation-path-broken': { primary: 'cx-rd-lead', secondary: 'cx-architect' },
-  'team-decision-violation': { primary: 'cx-rd-lead', secondary: 'cx-orchestrator' },
-  'cross-team-handoff-blocked': { primary: 'cx-rd-lead', secondary: null },
+  // Team governance signals — rd-lead retired (construct-rf26.11); route to
+  // cx-operations (owns dependency/ownership mapping) for resolution.
+  'team-understaffed': { primary: 'cx-operations', secondary: 'cx-orchestrator' },
+  'escalation-path-broken': { primary: 'cx-operations', secondary: 'cx-architect' },
+  'team-decision-violation': { primary: 'cx-operations', secondary: 'cx-orchestrator' },
+  'cross-team-handoff-blocked': { primary: 'cx-operations', secondary: null },
 };
 
 const ACTION_ROUTES = {
   'specialist-review': { primary: 'cx-reviewer', gateType: 'specialist-dispatch' },
-  'doctor-followup': { primary: 'cx-sre', gateType: 'operational-followup' },
-  'trace-review': { primary: 'cx-trace-reviewer', gateType: 'specialist-dispatch' },
-  'outcomes-aggregate': { primary: 'cx-data-engineer', gateType: 'maintenance' },
+  'doctor-followup': { primary: 'cx-operations', gateType: 'operational-followup' },
+  'trace-review': { primary: 'cx-reviewer', gateType: 'specialist-dispatch' },
+  'outcomes-aggregate': { primary: 'cx-engineer', gateType: 'maintenance' },
   'executive-signoff-required': { primary: 'cx-product-manager', gateType: 'executive-gate' },
   'structure-cleanup-proposal': { primary: 'cx-architect', gateType: 'human-approval' },
-  'graph-rebuild': { primary: 'cx-platform-engineer', gateType: 'maintenance' },
+  'graph-rebuild': { primary: 'cx-engineer', gateType: 'maintenance' },
 };
 
 /**
@@ -59,14 +65,14 @@ export function routeGap(gap) {
   const id = gap?.id ?? gap?.signal ?? '';
   const row = GAP_ROUTES[id];
   if (row) return { ...row, gateType: signOffGateForGap(id) };
-  return { primary: 'cx-oracle', secondary: null, gateType: 'human-approval' };
+  return { primary: 'cx-orchestrator', secondary: null, gateType: 'human-approval' };
 }
 
 /**
  * @param {string} actionKind
  */
 export function routeAction(actionKind) {
-  return ACTION_ROUTES[actionKind] ?? { primary: 'cx-oracle', gateType: 'human-approval' };
+  return ACTION_ROUTES[actionKind] ?? { primary: 'cx-orchestrator', gateType: 'human-approval' };
 }
 
 function signOffGateForGap(gapId) {

package/lib/oracle/synthesize.mjs

@@ -94,7 +94,7 @@ export function synthesizeVerdict(readModel) {
     ));
     recommendedActions.push(action(
       'trace-review',
-      'Dispatch cx-trace-reviewer to inspect degraded specialist outcomes',
+      'Dispatch cx-reviewer to inspect degraded specialist outcomes',
       { roles: degradedRoles, signOff: signOffMetadata({ id: 'outcomes-degradation' }, readModel.projectDir) },
     ));
   }