@geraldmaron/construct 1.1.0 → 1.2.0

package/lib/oracle/execute.mjs

@@ -0,0 +1,143 @@
+/**
+ * lib/oracle/execute.mjs — post-approve action executors for Oracle pending queue.
+ *
+ * Runs maintenance and L1 dispatch after human approval. Never performs git
+ * push/commit or destructive deletes.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+
+import { syncProjectAdapters } from '../adapters-sync.mjs';
+import { isConstructPackageRepo } from '../host-disposition.mjs';
+import { aggregateOutcomes } from '../outcomes/aggregate.mjs';
+import { recordAndMaybeInvoke } from '../roles/gateway.mjs';
+import { validateCapabilityRegistry } from '../registry/validate.mjs';
+import { writeRoutingArtifact } from './dispatch.mjs';
+import { routeAction } from './routing.mjs';
+
+function rolePendingPath(homeDir = homedir()) {
+  const root = process.env.CONSTRUCT_ROLES_ROOT || path.join(homeDir, '.cx');
+  return path.join(root, 'role-pending.jsonl');
+}
+
+function appendRolePending(entry, homeDir = homedir()) {
+  const file = rolePendingPath(homeDir);
+  const dir = path.dirname(file);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.appendFileSync(file, JSON.stringify(entry) + '\n', 'utf8');
+}
+
+async function dispatchSpecialist({ action, projectDir, homeDir, personaId, eventType }) {
+  const route = routeAction(action.kind);
+  const artifactPath = writeRoutingArtifact({
+    projectDir,
+    tickId: action.id,
+    synthesis: { verdict: 'approved', gaps: [], recommendedActions: [action] },
+    readModel: null,
+    route,
+  });
+
+  const prevRolesRoot = process.env.CONSTRUCT_ROLES_ROOT;
+  process.env.CONSTRUCT_ROLES_ROOT = path.join(homeDir, '.cx');
+
+  const event = {
+    project: projectDir,
+    cwd: projectDir,
+    summary: `[oracle] ${action.kind}: ${action.summary}`,
+    context: {
+      oracleActionId: action.id,
+      kind: action.kind,
+      artifactPath,
+      gateType: route.gateType,
+      requiredApprover: route.primary,
+    },
+  };
+
+  let gatewayResult = null;
+  try {
+    gatewayResult = await recordAndMaybeInvoke(eventType, event);
+  } catch {
+    gatewayResult = { recorded: false, escalated: false, reason: 'gateway-error' };
+  }
+
+  if (!gatewayResult?.escalated) {
+    appendRolePending({
+      ts: Date.now(),
+      personaId: personaId.replace(/^cx-/, ''),
+      cxId: personaId,
+      bdIssueId: gatewayResult?.bdIssueId ?? null,
+      fingerprint: `oracle-${action.id}`,
+      eventType,
+      summary: action.summary,
+      source: 'oracle-execute',
+      artifactPath,
+    }, homeDir);
+  }
+
+  if (prevRolesRoot === undefined) delete process.env.CONSTRUCT_ROLES_ROOT;
+  else process.env.CONSTRUCT_ROLES_ROOT = prevRolesRoot;
+
+  return {
+    ok: true,
+    artifactPath,
+    gateway: gatewayResult,
+    personaId,
+  };
+}
+
+/**
+ * Execute an approved Oracle pending action.
+ *
+ * @param {object} action — pending row from pending.jsonl
+ * @param {object} opts
+ */
+export async function executeApprovedAction(action, { rootDir, projectDir, homeDir, dryRun = false } = {}) {
+  if (dryRun) return { ok: true, dryRun: true, kind: action.kind };
+
+  const kind = action.kind;
+  switch (kind) {
+    case 'outcomes-aggregate': {
+      aggregateOutcomes(projectDir);
+      return { ok: true, kind, result: 'aggregated' };
+    }
+    case 'registry-validate': {
+      const report = validateCapabilityRegistry({ rootDir });
+      return { ok: report.valid, kind, errors: report.errors?.length ?? 0, warnings: report.warnings?.length ?? 0 };
+    }
+    case 'adapters-sync': {
+      if (!isConstructPackageRepo(projectDir)) {
+        return { ok: true, kind, skipped: true, reason: 'not-tool-repo' };
+      }
+      const result = syncProjectAdapters({ projectRoot: projectDir, packageRoot: rootDir, log: () => {} });
+      return { ok: !!result.synced, kind, hosts: result.hosts ?? [] };
+    }
+    case 'census-run': {
+      const script = path.join(rootDir, 'scripts', 'alignment', 'census.mjs');
+      if (!fs.existsSync(script)) return { ok: false, kind, error: 'census script missing' };
+      const { spawnSync } = await import('node:child_process');
+      const result = spawnSync(process.execPath, [script], { cwd: rootDir, encoding: 'utf8' });
+      return { ok: result.status === 0, kind, exitCode: result.status };
+    }
+    case 'specialist-review':
+      return dispatchSpecialist({
+        action, projectDir, homeDir, personaId: 'cx-reviewer', eventType: 'contract.violation',
+      });
+    case 'trace-review':
+      return dispatchSpecialist({
+        action, projectDir, homeDir, personaId: 'cx-trace-reviewer', eventType: 'outcomes.degraded',
+      });
+    case 'doctor-followup':
+      return dispatchSpecialist({
+        action, projectDir, homeDir, personaId: 'cx-sre', eventType: 'service.down',
+      });
+    case 'executive-signoff-required':
+    case 'structure-cleanup-proposal':
+      return dispatchSpecialist({
+        action, projectDir, homeDir, personaId: routeAction(kind).primary, eventType: 'oracle.approval',
+      });
+    default:
+      return { ok: false, kind, error: 'no-executor' };
+  }
+}

package/lib/oracle/gaps.mjs

@@ -0,0 +1,76 @@
+/**
+ * lib/oracle/gaps.mjs — human and machine-readable gap surfaces for Oracle.
+ *
+ * Groups latest verdict gaps into verdict-only (hygiene/meta) vs actionable
+ * auto-raise candidates. Does not file tracker beads.
+ */
+
+import { readLatestVerdict } from './verdicts.mjs';
+import { isVerdictOnlyGap, autoRaiseEnabledForGap } from './policy.mjs';
+
+const HYGIENE_HINTS = {
+  'beads-hygiene': 'Run `construct beads drift` to inspect stuck/stale beads.',
+  'workflow-misaligned': 'Run `construct workflow init` or `construct init` to align workflow state.',
+  'propagation-stale': 'Run `construct sync` to refresh platform propagation.',
+  'census-stale': 'Run `construct census` to refresh the fleet census.',
+  'outcomes-missing': 'Run `construct outcomes aggregate` when outcome data is available.',
+};
+
+/**
+ * @param {string} projectDir
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env]
+ * @returns {{ verdict: string|null, gaps: object[], verdictOnly: object[], actionable: object[] }}
+ */
+export function collectOracleGaps(projectDir, { env = process.env } = {}) {
+  const latest = readLatestVerdict(projectDir);
+  const gaps = Array.isArray(latest?.gaps) ? latest.gaps : [];
+  const verdictOnly = gaps.filter((g) => isVerdictOnlyGap(g));
+  const actionable = gaps.filter((g) => autoRaiseEnabledForGap(g, env));
+  return {
+    verdict: latest?.verdict ?? null,
+    gaps,
+    verdictOnly,
+    actionable,
+  };
+}
+
+/**
+ * @param {ReturnType<typeof collectOracleGaps>} data
+ * @returns {string}
+ */
+export function formatOracleGapsReport(data) {
+  const lines = [];
+  lines.push(`Oracle gaps · verdict: ${data.verdict ?? 'unknown'}`);
+  lines.push('');
+  if (!data.gaps.length) {
+    lines.push('No gaps in latest verdict.');
+    return lines.join('\n') + '\n';
+  }
+  if (data.verdictOnly.length) {
+    lines.push('Verdict-only (not filed to bd ready):');
+    for (const g of data.verdictOnly) {
+      lines.push(`  [${g.severity}] ${g.id}: ${g.detail}`);
+      const hint = HYGIENE_HINTS[g.id];
+      if (hint) lines.push(`    → ${hint}`);
+    }
+    lines.push('');
+  }
+  if (data.actionable.length) {
+    lines.push('Actionable (eligible for auto-raise when high):');
+    for (const g of data.actionable) {
+      lines.push(`  [${g.severity}] ${g.id}: ${g.detail}`);
+    }
+    lines.push('');
+  }
+  const other = data.gaps.filter((g) => !isVerdictOnlyGap(g) && !autoRaiseEnabledForGap(g));
+  if (other.length) {
+    lines.push('Other gaps (below auto-raise threshold or disabled):');
+    for (const g of other) {
+      lines.push(`  [${g.severity}] ${g.id}: ${g.detail}`);
+    }
+    lines.push('');
+  }
+  lines.push('Inspect: `construct oracle review` · Drift: `construct beads drift`');
+  return lines.join('\n') + '\n';
+}

package/lib/oracle/index.mjs

@@ -0,0 +1,84 @@
+/**
+ * lib/oracle/index.mjs — Oracle meta-controller daemon.
+ *
+ * Periodic tick over the read model with bounded-auto execution. Built on
+ * lib/daemons/contract.mjs safeguards. Disabled when CONSTRUCT_ORACLE=off.
+ * Heartbeat: ~/.cx/runtime/oracle/heartbeat.json
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+
+import { createDaemon } from '../daemons/contract.mjs';
+import { memoryCapMbFor } from '../resources/process-budget.mjs';
+import { runOracleTick, defaultRootDir } from './actions.mjs';
+
+export const KILLSWITCH_ENV = 'CONSTRUCT_ORACLE';
+
+function runtimeDir(homeDir = homedir()) {
+  return path.join(homeDir, '.cx', 'runtime', 'oracle');
+}
+
+export function heartbeatPath(homeDir = homedir()) {
+  return path.join(runtimeDir(homeDir), 'heartbeat.json');
+}
+
+export function lastTickPath(homeDir = homedir()) {
+  return path.join(runtimeDir(homeDir), 'last-tick.json');
+}
+
+function writeLastTick(tick, homeDir) {
+  const dir = runtimeDir(homeDir);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(lastTickPath(homeDir), JSON.stringify(tick, null, 2));
+}
+
+export function readLastTick(homeDir = homedir()) {
+  const file = lastTickPath(homeDir);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build a DaemonRunner for the Oracle meta-controller.
+ */
+export function buildOracleDaemon({
+  rootDir = defaultRootDir(),
+  projectDir = process.cwd(),
+  homeDir = homedir(),
+  intervalMs = 5 * 60_000,
+  dryRun = false,
+} = {}) {
+  return createDaemon({
+    name: 'oracle',
+    intervalMs,
+    killswitchEnv: KILLSWITCH_ENV,
+    heartbeatPath: heartbeatPath(homeDir),
+    lockPath: path.join(runtimeDir(homeDir), 'oracle.lock'),
+    maxRuntimeMs: 24 * 60 * 60 * 1000,
+    maxIdleTicks: 3,
+    memoryCapMb: memoryCapMbFor('oracle', projectDir),
+    async tick() {
+      const result = await runOracleTick({ rootDir, projectDir, homeDir, dryRun });
+      writeLastTick(result.tick, homeDir);
+      const didWork = result.tick.executed.length > 0
+        || result.tick.queued.length > 0
+        || (result.tick.beadsRaised?.length ?? 0) > 0
+        || result.verdict !== 'healthy';
+      return { didWork };
+    },
+  });
+}
+
+/**
+ * Run the Oracle daemon until idle shutdown, killswitch, or max runtime.
+ */
+export async function runOracleDaemon(opts = {}) {
+  const daemon = buildOracleDaemon(opts);
+  return daemon.run();
+}

package/lib/oracle/issues.mjs

@@ -0,0 +1,164 @@
+/**
+ * lib/oracle/issues.mjs — idempotent beads issue raising from Oracle gaps.
+ *
+ * Persistent gapId fingerprints and open-bead lookup prevent duplicate tracker
+ * spam. Verdict-only hygiene gaps never reach bd create — see policy.mjs.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { runBd } from '../beads-client.mjs';
+import { autoRaiseEnabledForGap } from './policy.mjs';
+import { routeGap } from './routing.mjs';
+
+const RAISED_FILE = 'raised-issues.jsonl';
+const MAX_AUTO_RAISE_PER_TICK = 5;
+const OPEN_STATUSES = new Set(['open', 'in_progress']);
+
+function raisedPath(projectDir) {
+  return path.join(projectDir, '.cx', 'oracle', RAISED_FILE);
+}
+
+export function gapFingerprint(gap) {
+  return String(gap?.id ?? 'unknown');
+}
+
+export function oracleBeadTitlePrefix(gapId) {
+  return `[oracle/${gapId}]`;
+}
+
+function readRaised(projectDir) {
+  const file = raisedPath(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 appendRaised(projectDir, record) {
+  const dir = path.join(projectDir, '.cx', 'oracle');
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.appendFileSync(raisedPath(projectDir), JSON.stringify(record) + '\n', 'utf8');
+}
+
+function parseBdList(output) {
+  try {
+    const parsed = JSON.parse(String(output ?? ''));
+    if (Array.isArray(parsed)) return parsed;
+    if (Array.isArray(parsed?.issues)) return parsed.issues;
+  } catch { /* empty */ }
+  return [];
+}
+
+/**
+ * @param {string} projectDir
+ * @param {string} gapId
+ * @returns {Promise<{ id: string, title: string }|null>}
+ */
+export async function findOpenOracleBeadForGap(projectDir, gapId) {
+  const prefix = oracleBeadTitlePrefix(gapId);
+  const matches = [];
+  for (const status of OPEN_STATUSES) {
+    const result = await runBd(['list', '--json', `--status=${status}`], {
+      actor: 'oracle',
+      silent: true,
+      timeoutSeconds: 15,
+      commandTimeoutSeconds: 30,
+    });
+    if (!result.success) continue;
+    for (const bead of parseBdList(result.output)) {
+      const title = String(bead?.title ?? '');
+      if (title.startsWith(prefix)) {
+        matches.push({ id: bead.id, title });
+      }
+    }
+  }
+  if (!matches.length) return null;
+  return matches[0];
+}
+
+export function alreadyRaised(projectDir, fingerprint) {
+  return readRaised(projectDir).some((r) => r.fingerprint === fingerprint && r.beadId);
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.projectDir
+ * @param {{ id: string, severity: string, detail: string, signal?: string }} opts.gap
+ * @param {boolean} [opts.dryRun]
+ * @returns {Promise<{ ok: boolean, skipped?: boolean, reason?: string, beadId?: string|null, fingerprint?: string }>}
+ */
+export async function raiseIssueForGap({ projectDir, gap, dryRun = false }) {
+  if (!autoRaiseEnabledForGap(gap)) {
+    return { ok: true, skipped: true, reason: 'verdict-only', fingerprint: gapFingerprint(gap) };
+  }
+
+  const fingerprint = gapFingerprint(gap);
+  if (alreadyRaised(projectDir, fingerprint)) {
+    return { ok: true, skipped: true, reason: 'already-raised', fingerprint };
+  }
+
+  const openBead = await findOpenOracleBeadForGap(projectDir, gap.id);
+  if (openBead) {
+    return { ok: true, skipped: true, reason: 'open-bead-exists', beadId: openBead.id, fingerprint };
+  }
+
+  const route = routeGap(gap);
+  const title = `${oracleBeadTitlePrefix(gap.id)} ${String(gap.detail).slice(0, 100)}`;
+  const body = JSON.stringify({
+    gapId: gap.id,
+    severity: gap.severity,
+    signal: gap.signal ?? null,
+    detail: gap.detail,
+    route: route.primary,
+    fingerprint,
+    raisedAt: new Date().toISOString(),
+  }, null, 2);
+
+  if (dryRun) {
+    return { ok: true, dryRun: true, fingerprint, beadId: null };
+  }
+
+  const labels = ['oracle', 'construct-hygiene', gap.severity].join(',');
+  const result = await runBd(
+    ['create', title, '-t', 'task', '-l', labels, '-d', body],
+    { actor: 'oracle', silent: true, timeoutSeconds: 15, commandTimeoutSeconds: 30 },
+  );
+
+  if (!result.success) {
+    return { ok: false, reason: result.error || 'bd-create-failed', fingerprint };
+  }
+
+  const match = String(result.output || '').match(/Created issue:\s*([\w-]+)/);
+  const beadId = match ? match[1] : null;
+  appendRaised(projectDir, {
+    fingerprint,
+    gapId: gap.id,
+    beadId,
+    raisedAt: new Date().toISOString(),
+    title,
+  });
+  return { ok: true, beadId, fingerprint };
+}
+
+/**
+ * Auto-raise beads for actionable high-severity gaps with idempotency and rate limit.
+ *
+ * @param {object} opts
+ * @param {string} opts.projectDir
+ * @param {object[]} opts.gaps
+ * @param {boolean} [opts.dryRun]
+ */
+export async function raiseIssuesForGaps({ projectDir, gaps, dryRun = false }) {
+  const actionable = gaps.filter((g) => autoRaiseEnabledForGap(g));
+  const raised = [];
+  for (const gap of actionable.slice(0, MAX_AUTO_RAISE_PER_TICK)) {
+    const result = await raiseIssueForGap({ projectDir, gap, dryRun });
+    raised.push({ gapId: gap.id, ...result });
+  }
+  for (const gap of gaps.filter((g) => g.severity === 'high' && !autoRaiseEnabledForGap(g))) {
+    raised.push({ gapId: gap.id, ok: true, skipped: true, reason: 'verdict-only', fingerprint: gapFingerprint(gap) });
+  }
+  return raised;
+}

package/lib/oracle/org-graph.mjs

@@ -0,0 +1,170 @@
+/**
+ * lib/oracle/org-graph.mjs — org-in-a-box propagation graph collector.
+ *
+ * Loads policy inventory, workflow gates, intake sign-offs, and capability
+ * human gates. Produces findings for synthesizeVerdict — no side effects.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { alignmentFindings } from '../workflow-state.mjs';
+import { loadCapabilityRegistry } from '../registry/validate.mjs';
+import { isConstructPackageRepo } from '../host-disposition.mjs';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.resolve(MODULE_DIR, '../..');
+
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function collectPolicyInventory(rootDir) {
+  const file = path.join(rootDir, 'specialists', 'policy-inventory.json');
+  const data = readJsonSafe(file);
+  if (!data) return { present: false, count: 0, policies: [] };
+  const policies = data.policies ?? [];
+  const orphans = [];
+  for (const p of policies) {
+    if (p.source && p.source !== 'built-in' && !p.source.startsWith('specialists/')) {
+      const rulePath = path.join(rootDir, p.source);
+      if (!fs.existsSync(rulePath)) orphans.push(p.id);
+    }
+  }
+  return { present: true, count: policies.length, orphanPolicyIds: orphans };
+}
+
+function collectWorkflow(projectDir) {
+  const file = path.join(projectDir, '.cx', 'workflow.json');
+  const workflow = readJsonSafe(file);
+  if (!workflow) return { present: false, findings: alignmentFindings(null) };
+  return { present: true, workflow, findings: alignmentFindings(workflow) };
+}
+
+function collectIntakeSignoffs(projectDir) {
+  const pendingDir = path.join(projectDir, '.cx', 'intake', 'pending');
+  if (!fs.existsSync(pendingDir)) return { pendingCount: 0, legalPending: [], approvalPending: [] };
+  const legalPending = [];
+  const approvalPending = [];
+  for (const name of fs.readdirSync(pendingDir)) {
+    if (!name.endsWith('.json')) continue;
+    const packet = readJsonSafe(path.join(pendingDir, name));
+    if (!packet) continue;
+    const triage = packet.triage ?? {};
+    if (triage.intakeType === 'legal-compliance' || triage.primaryOwner === 'legal-compliance') {
+      legalPending.push({ id: packet.id ?? name.replace(/\.json$/, ''), triage });
+    }
+    if (triage.requiresApproval === true) {
+      approvalPending.push({ id: packet.id ?? name.replace(/\.json$/, ''), triage });
+    }
+  }
+  return { pendingCount: legalPending.length + approvalPending.length, legalPending, approvalPending };
+}
+
+function collectCapabilityGates(rootDir) {
+  const raw = loadCapabilityRegistry({ rootDir });
+  const unvalidated = [];
+  for (const cap of raw.capabilities ?? []) {
+    if (cap.criticality !== 'P0' && cap.criticality !== 'P1') continue;
+    if (!cap.lastValidated) {
+      unvalidated.push({ id: cap.id, criticality: cap.criticality, humanGate: cap.humanGate ?? null });
+    }
+  }
+  return { count: (raw.capabilities ?? []).length, unvalidatedP0P1: unvalidated };
+}
+
+function collectPropagationSignals({ rootDir, projectDir, parity, registryValidate }) {
+  const registryPath = path.join(rootDir, 'specialists', 'registry.json');
+  let registryMtime = null;
+  try {
+    registryMtime = fs.statSync(registryPath).mtimeMs;
+  } catch { /* ignore */ }
+
+  const staleSurfaces = (parity?.surfaces ?? []).filter((s) => s.stale || s.status === 'drift');
+  const registryFailed = registryValidate && !registryValidate.valid;
+  const needsPropagation = (!parity?.ok && !parity?.skipped) || staleSurfaces.length > 0 || registryFailed;
+
+  return {
+    registryMtime,
+    needsPropagation,
+    staleSurfaceCount: staleSurfaces.length,
+    registryFailed,
+  };
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.rootDir
+ * @param {string} opts.projectDir
+ * @param {object} [opts.parity]
+ * @param {object} [opts.registryValidate]
+ */
+export function collectOrgGraph({ rootDir = PACKAGE_ROOT, projectDir, parity, registryValidate }) {
+  return {
+    policyInventory: collectPolicyInventory(rootDir),
+    workflow: collectWorkflow(projectDir),
+    intakeSignoffs: collectIntakeSignoffs(projectDir),
+    capabilityGates: collectCapabilityGates(rootDir),
+    propagation: collectPropagationSignals({ rootDir, projectDir, parity, registryValidate }),
+    isToolRepo: isConstructPackageRepo(projectDir),
+  };
+}
+
+/**
+ * Convert org graph into supplemental gap descriptors for synthesize.
+ *
+ * @param {object} orgGraph
+ * @returns {object[]}
+ */
+export function orgGraphToGapHints(orgGraph) {
+  const hints = [];
+  if (orgGraph.propagation?.needsPropagation) {
+    hints.push({ id: 'propagation-stale', severity: 'medium', signal: 'org-graph', detail: 'Upstream registry or parity drift — downstream surfaces may be stale' });
+  }
+  if (orgGraph.policyInventory?.orphanPolicyIds?.length) {
+    hints.push({
+      id: 'policy-coverage-gap',
+      severity: 'medium',
+      signal: 'policy-inventory',
+      detail: `${orgGraph.policyInventory.orphanPolicyIds.length} policy source(s) missing on disk`,
+    });
+  }
+  for (const f of orgGraph.workflow?.findings ?? []) {
+    if (f.severity === 'HIGH') {
+      hints.push({
+        id: 'workflow-misaligned',
+        severity: 'high',
+        signal: 'workflow',
+        detail: f.issue,
+        gateType: 'executive-gate',
+        task: f.task ?? null,
+      });
+    }
+  }
+  if (orgGraph.intakeSignoffs?.legalPending?.length) {
+    hints.push({
+      id: 'legal-review-pending',
+      severity: 'high',
+      signal: 'intake',
+      detail: `${orgGraph.intakeSignoffs.legalPending.length} legal-compliance intake packet(s) awaiting sign-off`,
+      gateType: 'legal-compliance',
+    });
+  }
+  const unvalidated = orgGraph.capabilityGates?.unvalidatedP0P1 ?? [];
+  const p0Unvalidated = unvalidated.filter((c) => c.criticality === 'P0');
+  if (p0Unvalidated.length) {
+    hints.push({
+      id: 'capability-unvalidated',
+      severity: 'medium',
+      signal: 'capabilities',
+      detail: `P0/P1 capabilities without validation stamp: ${p0Unvalidated.map((c) => c.id).slice(0, 5).join(', ')}`,
+      gateType: 'capability-human-gate',
+    });
+  }
+  return hints;
+}