@geraldmaron/construct 1.2.3 → 1.3.0

package/lib/models/execution-capability-profile.mjs

@@ -3,7 +3,7 @@
  * record (construct-6zga.1.8).
  *
  * Consolidates the four formerly-scattered capability producers into one
- * serializable, versioned record that chat (resolveCapabilityTier) and specialist
+ * serializable, versioned record that model routing (resolveCapabilityTier) and specialist
  * prompt composition (resolveModelOperatingProfile via lib/prompt-composer.js) both
  * consume. It is keyed by provider, requested/resolved model, adapter protocol, and
  * observation time. Every capability declares an evidence source
@@ -57,8 +57,8 @@ export function providerGroupForModel(model) {
   return seg || 'unknown';
 }
 
-// Adapter protocol mirrors the dispatch in apps/chat/engine/ai-sdk-agent.mjs:
-// Anthropic uses its native messages API, OpenAI and Copilot use chat completions,
+// Adapter protocol mirrors provider worker dispatch:
+// Anthropic uses its native messages API, OpenAI and Copilot use completions,
 // and every other provider goes through the OpenAI-compatible shim.
 
 function adapterProtocolForGroup(group) {

package/lib/models/execution-policy.mjs

@@ -81,11 +81,10 @@ function oneOf(allowed, value, fallback) {
   return allowed.includes(value) ? value : fallback;
 }
 
-// The chat turn overlay (lib/chat/transparency.mjs) speaks the orchestration
-// vocabulary (INTENT_CLASSES, risk flags, externalResearch). These helpers map it
+// Routing overlays speak the orchestration vocabulary (INTENT_CLASSES, risk flags,
+// externalResearch). These helpers map that vocabulary
 // onto the compiler's stable input enums so the compiler stays decoupled from
-// routing changes. A turn that follows a failed tool result is the recovery case
-// the loop signals with toolFailure.
+// routing changes. A turn that follows a failed tool result is the recovery case.
 
 export function normalizePolicyIntent({ intent = null, assumptionsBlocked = false, toolFailure = false } = {}) {
   if (toolFailure === true) return 'tool-failure';
@@ -240,10 +239,10 @@ export function compileExecutionPolicy({
 }
 
 /**
- * Compile a policy directly from a chat turn overlay (lib/chat/transparency.mjs),
+ * Compile a policy directly from a routing overlay,
  * normalizing its routing vocabulary into the compiler's input enums first.
  */
-export function compilePolicyFromOverlay({ profile = null, overlay = null, toolFailure = false } = {}) {
+export function compilePolicyFromRoutingOverlay({ profile = null, overlay = null, toolFailure = false } = {}) {
   const intent = normalizePolicyIntent({
     intent: overlay?.intent,
     assumptionsBlocked: overlay?.assumptionsBlocked === true,
@@ -257,6 +256,8 @@ export function compilePolicyFromOverlay({ profile = null, overlay = null, toolF
   return compileExecutionPolicy({ profile, intent, risk, evidenceRequirement });
 }
 
+export const compilePolicyFromOverlay = compilePolicyFromRoutingOverlay;
+
 /**
  * Hand-rolled validator (no ajv — Construct stays dependency-free at startup).
  * Returns { valid, errors } against schemas/execution-policy.schema.json.

package/lib/models/provider-poll.mjs

@@ -71,8 +71,16 @@ function openRouterCapabilities(model) {
   };
 }
 
+function resolveSecretOrNull(varNames, opts) {
+  try {
+    return resolveFirstSecret(varNames, opts);
+  } catch {
+    return null;
+  }
+}
+
 export async function pollOpenRouter({ env = process.env } = {}) {
-  const apiKey = resolveFirstSecret(['OPENROUTER_API_KEY', 'OPEN_ROUTER_API_KEY'], { env });
+  const apiKey = resolveSecretOrNull(['OPENROUTER_API_KEY', 'OPEN_ROUTER_API_KEY'], { env, allowAmbient: env === process.env });
   const headers = apiKey ? { Authorization: `Bearer ${apiKey}` } : {};
   const data = await fetchJson('https://openrouter.ai/api/v1/models', { headers });
   if (!data) return null;
@@ -80,10 +88,15 @@ export async function pollOpenRouter({ env = process.env } = {}) {
   const models = [];
   for (const m of list) {
     if (!m?.id) continue;
+    const outputs = m.architecture?.output_modalities;
+    if (Array.isArray(outputs) && outputs.length && !outputs.includes('text')) continue;
+    if (/(embed|rerank|whisper|tts|dall-e|moderation|transcribe|sora)/i.test(m.id)) continue;
     const free = isFreePricing(m.pricing);
     const input = Number(m.pricing?.prompt);
     const output = Number(m.pricing?.completion);
     const caps = openRouterCapabilities(m);
+    const context = Number(m.context_length) || null;
+    if (!free && context && context < 8000) continue;
     models.push({
       id: `openrouter/${m.id}`,
       label: m.name || m.id,
@@ -92,11 +105,12 @@ export async function pollOpenRouter({ env = process.env } = {}) {
       pricing: Number.isFinite(input) && Number.isFinite(output)
         ? { input: input * 1_000_000, output: output * 1_000_000 }
         : null,
-      context: Number(m.context_length) || null,
+      context,
       reasoning: caps.reasoning,
       tools: caps.tools,
       toolsKnown: true,
       vision: caps.vision,
+      architecture: m.architecture || null,
       source: 'live',
     });
   }
@@ -110,7 +124,7 @@ export async function pollOpenRouter({ env = process.env } = {}) {
 const OPENAI_NON_CHAT = /(embedding|whisper|tts|audio|realtime|image|dall-e|moderation|search|babbage|davinci|transcribe|sora)/i;
 
 export async function pollOpenAI({ env = process.env } = {}) {
-  const apiKey = resolveFirstSecret(['OPENAI_API_KEY'], { env });
+  const apiKey = resolveSecretOrNull(['OPENAI_API_KEY'], { env, allowAmbient: env === process.env });
   if (!apiKey) return null;
   const data = await fetchJson('https://api.openai.com/v1/models', {
     headers: { Authorization: `Bearer ${apiKey}` },
@@ -141,7 +155,7 @@ export async function pollOpenAI({ env = process.env } = {}) {
 }
 
 export async function pollAnthropic({ env = process.env } = {}) {
-  const apiKey = resolveFirstSecret(['ANTHROPIC_API_KEY'], { env });
+  const apiKey = resolveSecretOrNull(['ANTHROPIC_API_KEY'], { env, allowAmbient: env === process.env });
   if (!apiKey) return null;
   const data = await fetchJson('https://api.anthropic.com/v1/models?limit=100', {
     headers: { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01' },

package/lib/opencode-config.mjs

@@ -48,6 +48,43 @@ export function sanitizeOpenCodeConfig(config) {
   return sanitized;
 }
 
+// op run resolves only the launch env-file, never values baked into config
+// JSON. A literal `op://` reference (or a build-time __PLACEHOLDER__) left in a
+// credential field is therefore sent to OpenRouter verbatim, which 401s. Only
+// `{env:VAR}` (resolved by OpenCode) and concrete keys count as real auth.
+
+function isUnresolvedSecretRef(value) {
+  return typeof value === 'string' && (value.includes('op://') || value.includes('__OPENROUTER_API_KEY__'));
+}
+
+function openRouterHasAuth(provider = {}) {
+  const apiKey = provider.apiKey;
+  if (typeof apiKey === 'string' && apiKey.length > 0 && !isUnresolvedSecretRef(apiKey)) {
+    return true;
+  }
+  const auth = provider.options?.headers?.Authorization;
+  return typeof auth === 'string' && auth.length > 0 && !isUnresolvedSecretRef(auth);
+}
+
+export function ensureOpenRouterProviderAuth(config) {
+  if (!config?.provider?.openrouter) return config;
+  const provider = config.provider.openrouter;
+
+  // A broken Authorization header overrides the working apiKey at request time,
+  // so strip it before deciding whether the provider still needs an env-ref key.
+
+  const authHeader = provider.options?.headers?.Authorization;
+  if (isUnresolvedSecretRef(authHeader)) {
+    delete provider.options.headers.Authorization;
+  }
+  if (openRouterHasAuth(provider)) return config;
+  config.provider.openrouter = {
+    ...provider,
+    apiKey: '{env:OPENROUTER_API_KEY}',
+  };
+  return config;
+}
+
 /**
  * Maps Construct internal tiers (fast, standard, reasoning) to OpenCode model configurations.
  */
@@ -124,7 +161,7 @@ export function writeOpenCodeConfig(config, file = findOpenCodeConfigPath()) {
     if (config.models.some(m => m.provider === 'openrouter')) {
       config.provider.openrouter = config.provider.openrouter || {
         baseUrl: "https://openrouter.ai/api/v1",
-        apiKey: "__OPENROUTER_API_KEY__"
+        apiKey: "{env:OPENROUTER_API_KEY}"
       };
     }
     if (config.models.some(m => m.provider === 'ollama')) {
@@ -204,6 +241,24 @@ export function writeOpenCodeConfig(config, file = findOpenCodeConfigPath()) {
   // The relevant models should only be defined under provider.<name>.models
   delete config.models;
 
+  ensureOpenRouterProviderAuth(config);
+
+  // The plugin array is hand- and CLI-editable, so it accumulates junk: stale
+  // toolkit paths from moved checkouts and stray CLI tokens (e.g. a literal
+  // "list"). A non-existent path entry can break plugin loading outright. Keep
+  // existing file-path plugins and plausible package specifiers, deduped.
+
+  if (Array.isArray(config.plugin)) {
+    const seen = new Set();
+    config.plugin = config.plugin.filter((entry) => {
+      if (typeof entry !== "string" || !entry.trim() || seen.has(entry)) return false;
+      seen.add(entry);
+      const isPath = /^([./~]|[A-Za-z]:[\\/])/.test(entry) || /\.[cm]?js$/.test(entry);
+      if (isPath) return fs.existsSync(entry);
+      return entry.length > 2 && (/^@/.test(entry) || /[-/]/.test(entry));
+    });
+  }
+
   fs.writeFileSync(target, `${JSON.stringify(sanitizeOpenCodeConfig(config), null, 2)}\n`, "utf8");
   return target;
 }

package/lib/opencode-runtime-plugin.mjs

@@ -5,6 +5,7 @@
  * records each as a telemetry trace, and applies model fallback on rate-limit errors.
  */
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { loadRegistry } from './registry/loader.mjs';
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
@@ -416,9 +417,7 @@ function buildHostConstraints() {
 
 function readRegistryModels(rootDir) {
   try {
-    const registryPath = join(rootDir, "specialists", "registry.json");
-    if (!existsSync(registryPath)) return {};
-    const registry = JSON.parse(readFileSync(registryPath, "utf8"));
+    const registry = loadRegistry({ rootDir, skipValidation: true });
     return registry?.models ?? {};
   } catch {
     return {};
@@ -759,13 +758,17 @@ async function emitRuntimeTrace(event, { client, env = process.env }) {
       await ingest.flush();
     }
   } catch {
-    await client?.app?.log?.({
-      body: {
-        service: "construct",
-        level: "warn",
-        message: "OpenCode runtime telemetry failed before delivery.",
-      },
-    });
+    try {
+      await client?.app?.log?.({
+        body: {
+          service: "construct",
+          level: "warn",
+          message: "OpenCode runtime telemetry failed before delivery.",
+        },
+      });
+    } catch {
+      // best effort: telemetry failure must not block fallback handling
+    }
   }
 }
 

package/lib/oracle/artifact-gate.mjs

@@ -49,6 +49,10 @@ function collectBypassArtifacts(projectDir) {
 }
 
 function collectReviewerGaps(projectDir) {
+  const agentLog = path.join(projectDir, '.cx', 'agent-log.jsonl');
+  if (!fs.existsSync(agentLog)) {
+    return { gaps: [], armed: false };
+  }
   const roots = [
     path.join(projectDir, 'docs', 'specs', 'prd'),
     path.join(projectDir, 'docs', 'prd'),
@@ -70,12 +74,12 @@ function collectReviewerGaps(projectDir) {
       }
     }
   }
-  return gaps.slice(0, 20);
+  return { gaps: gaps.slice(0, 20), armed: true };
 }
 
 export function collectArtifactGateSignals({ rootDir, projectDir }) {
   const bypassed = collectBypassArtifacts(projectDir);
-  const reviewerGaps = collectReviewerGaps(projectDir);
+  const { gaps: reviewerGaps, armed: reviewerGateArmed } = collectReviewerGaps(projectDir);
 
   let specialistAudit = { present: false, pass: true, crossCheckCount: 0 };
   if (isConstructPackageRepo(projectDir)) {
@@ -87,8 +91,13 @@ export function collectArtifactGateSignals({ rootDir, projectDir }) {
         crossCheckCount: audit.crossCheckIssues?.length ?? 0,
         crossCheckIssues: (audit.crossCheckIssues ?? []).slice(0, 5),
       };
-    } catch {
-      specialistAudit = { present: true, pass: false, crossCheckCount: -1 };
+    } catch (err) {
+      specialistAudit = {
+        present: true,
+        pass: false,
+        crossCheckCount: 0,
+        error: err?.message ?? String(err),
+      };
     }
   }
 
@@ -97,6 +106,7 @@ export function collectArtifactGateSignals({ rootDir, projectDir }) {
     bypassCount: bypassed.length,
     reviewerGaps,
     reviewerGapCount: reviewerGaps.length,
+    reviewerGateArmed,
     specialistAudit,
   };
 }

package/lib/oracle/cli.mjs

@@ -21,6 +21,7 @@ import { runOracleTick, listPending, approvePending, defaultRootDir } from './ac
 import { collectOracleGaps, formatOracleGapsReport } from './gaps.mjs';
 import { reconcileOracleHygieneBeads } from './reconcile.mjs';
 import { doctorRoot } from '../config/xdg.mjs';
+import { writeLastTick } from './index.mjs';
 
 const MODULE_FILE = fileURLToPath(import.meta.url);
 
@@ -87,6 +88,7 @@ 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 (!dryRun) writeLastTick(result.tick, homeDir);
   if (json) {
     process.stdout.write(JSON.stringify(result, null, 2) + '\n');
     return 0;

package/lib/oracle/dispatch.mjs

@@ -9,6 +9,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { routeGap, routeAction } from './routing.mjs';
+import { resolveRemediationDispatch } from './remediation-dispatch.mjs';
 
 export function routingDir(projectDir) {
   return path.join(projectDir, '.cx', 'oracle', 'routing');
@@ -28,9 +29,16 @@ export function buildRoutingArtifact({ synthesis, readModel, tickId, route }) {
 
   for (const gap of synthesis.gaps ?? []) {
     const r = routeGap(gap);
+    const dispatch = gap.remediationRoute?.mode
+      ? gap.remediationRoute
+      : resolveRemediationDispatch(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})` : ''}`);
+    lines.push(`    dispatch: ${dispatch.mode}${dispatch.teamRouting?.involvedTeams?.length ? ` (teams: ${dispatch.teamRouting.involvedTeams.join(', ')})` : ''}`);
+    if (dispatch.mode === 'swarm' && dispatch.specialists?.length) {
+      lines.push(`    swarm: ${dispatch.specialists.join(', ')}`);
+    }
     if (r.gateType) lines.push(`    gate: ${r.gateType}`);
   }
 
@@ -50,6 +58,15 @@ export function buildRoutingArtifact({ synthesis, readModel, tickId, route }) {
   if (route?.primary) {
     lines.push('', `DISPATCH TARGET: ${route.primary}`);
   }
+  if (route?.mode) {
+    lines.push(`DISPATCH MODE: ${route.mode}`);
+    if (route.mode === 'swarm' && route.specialists?.length) {
+      lines.push(`SWARM SPECIALISTS: ${route.specialists.join(', ')}`);
+    }
+    if (route.teamRouting?.involvedTeams?.length) {
+      lines.push(`INVOLVED TEAMS: ${route.teamRouting.involvedTeams.join(', ')}`);
+    }
+  }
 
   lines.push('', 'BLOCKED:', '  none (deterministic routing artifact — LLM dispatch is approve-gated)');
   return lines.join('\n');
@@ -76,6 +93,6 @@ export function maybeWriteHighSeverityRouting({ projectDir, tick, synthesis, rea
   if (!hasHigh) return null;
   const tickId = tick.at ?? new Date().toISOString();
   const primaryGap = synthesis.gaps.find((g) => g.severity === 'high');
-  const route = routeGap(primaryGap);
+  const route = primaryGap?.remediationRoute ?? routeGap(primaryGap);
   return writeRoutingArtifact({ projectDir, tickId, synthesis, readModel, route });
 }

package/lib/oracle/execute.mjs

@@ -16,6 +16,7 @@ import { recordAndMaybeInvoke } from '../roles/gateway.mjs';
 import { validateCapabilityRegistry } from '../registry/validate.mjs';
 import { writeRoutingArtifact } from './dispatch.mjs';
 import { routeAction } from './routing.mjs';
+import { resolveRemediationDispatch } from './remediation-dispatch.mjs';
 import { doctorRoot } from '../config/xdg.mjs';
 
 function rolePendingPath(homeDir = homedir()) {
@@ -30,14 +31,14 @@ function appendRolePending(entry, homeDir = homedir()) {
   fs.appendFileSync(file, JSON.stringify(entry) + '\n', 'utf8');
 }
 
-async function dispatchSpecialist({ action, projectDir, homeDir, personaId, eventType }) {
+async function dispatchSpecialist({ action, projectDir, homeDir, personaId, eventType, dispatch = null }) {
   const route = routeAction(action.kind);
   const artifactPath = writeRoutingArtifact({
     projectDir,
     tickId: action.id,
     synthesis: { verdict: 'approved', gaps: [], recommendedActions: [action] },
     readModel: null,
-    route,
+    route: dispatch ?? route,
   });
 
   const prevRolesRoot = process.env.CONSTRUCT_ROLES_ROOT;
@@ -53,6 +54,8 @@ async function dispatchSpecialist({ action, projectDir, homeDir, personaId, even
       artifactPath,
       gateType: route.gateType,
       requiredApprover: route.primary,
+      dispatchMode: dispatch?.mode ?? 'static',
+      involvedTeams: dispatch?.teamRouting?.involvedTeams ?? [],
     },
   };
 
@@ -69,11 +72,12 @@ async function dispatchSpecialist({ action, projectDir, homeDir, personaId, even
       personaId: personaId.replace(/^cx-/, ''),
       cxId: personaId,
       bdIssueId: gatewayResult?.bdIssueId ?? null,
-      fingerprint: `oracle-${action.id}`,
+      fingerprint: `oracle-${action.id}-${personaId}`,
       eventType,
       summary: action.summary,
       source: 'oracle-execute',
       artifactPath,
+      dispatchMode: dispatch?.mode ?? 'static',
     }, homeDir);
   }
 
@@ -88,6 +92,34 @@ async function dispatchSpecialist({ action, projectDir, homeDir, personaId, even
   };
 }
 
+async function dispatchRemediation({ action, projectDir, homeDir, eventType, personaId = null }) {
+  const dispatch = resolveRemediationDispatch(action, { projectDir });
+  if (dispatch.mode === 'swarm') {
+    const results = [];
+    for (const specialistId of dispatch.specialists) {
+      results.push(await dispatchSpecialist({
+        action, projectDir, homeDir, personaId: specialistId, eventType, dispatch,
+      }));
+    }
+    return {
+      ok: true,
+      mode: 'swarm',
+      specialists: dispatch.specialists,
+      teamRouting: dispatch.teamRouting,
+      results,
+    };
+  }
+  const result = await dispatchSpecialist({
+    action,
+    projectDir,
+    homeDir,
+    personaId: personaId ?? dispatch.primary,
+    eventType,
+    dispatch,
+  });
+  return { ...result, mode: 'static', teamRouting: dispatch.teamRouting };
+}
+
 /**
  * Execute an approved Oracle pending action.
  *
@@ -122,20 +154,20 @@ export async function executeApprovedAction(action, { rootDir, projectDir, homeD
       return { ok: result.status === 0, kind, exitCode: result.status };
     }
     case 'specialist-review':
-      return dispatchSpecialist({
+      return dispatchRemediation({
         action, projectDir, homeDir, personaId: 'cx-reviewer', eventType: 'contract.violation',
       });
     case 'trace-review':
-      return dispatchSpecialist({
+      return dispatchRemediation({
         action, projectDir, homeDir, personaId: 'cx-trace-reviewer', eventType: 'outcomes.degraded',
       });
     case 'doctor-followup':
-      return dispatchSpecialist({
+      return dispatchRemediation({
         action, projectDir, homeDir, personaId: 'cx-sre', eventType: 'service.down',
       });
     case 'executive-signoff-required':
     case 'structure-cleanup-proposal':
-      return dispatchSpecialist({
+      return dispatchRemediation({
         action, projectDir, homeDir, personaId: routeAction(kind).primary, eventType: 'oracle.approval',
       });
     default:

package/lib/oracle/index.mjs

@@ -29,7 +29,7 @@ export function lastTickPath(homeDir = homedir()) {
   return path.join(runtimeDir(homeDir), 'last-tick.json');
 }
 
-function writeLastTick(tick, homeDir) {
+export function writeLastTick(tick, homeDir = homedir()) {
   const dir = runtimeDir(homeDir);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
   fs.writeFileSync(lastTickPath(homeDir), JSON.stringify(tick, null, 2));

package/lib/oracle/org-graph.mjs

@@ -12,6 +12,7 @@ import { fileURLToPath } from 'node:url';
 import { alignmentFindings } from '../workflow-state.mjs';
 import { loadCapabilityRegistry } from '../registry/validate.mjs';
 import { isConstructPackageRepo } from '../host-disposition.mjs';
+import { loadRegistry } from '../registry/loader.mjs';
 
 const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = path.resolve(MODULE_DIR, '../..');
@@ -25,10 +26,14 @@ function readJsonSafe(filePath) {
 }
 
 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 ?? [];
+  let policies = [];
+  try {
+    const registry = loadRegistry({ rootDir, skipValidation: true });
+    const raw = registry.policies || {};
+    policies = Array.isArray(raw) ? raw : Object.values(raw);
+  } catch {
+    return { present: false, count: 0, policies: [] };
+  }
   const orphans = [];
   for (const p of policies) {
     if (p.source && p.source !== 'built-in' && !p.source.startsWith('specialists/')) {
@@ -79,7 +84,7 @@ function collectCapabilityGates(rootDir) {
 }
 
 function collectPropagationSignals({ rootDir, projectDir, parity, registryValidate }) {
-  const registryPath = path.join(rootDir, 'specialists', 'registry.json');
+  const registryPath = path.join(rootDir, 'specialists', 'org');
   let registryMtime = null;
   try {
     registryMtime = fs.statSync(registryPath).mtimeMs;

package/lib/oracle/policy.mjs

@@ -30,6 +30,12 @@ export const VERDICT_ONLY_GAP_IDS = new Set([
   'propagation-stale',
   'census-stale',
   'outcomes-missing',
+  // Team governance signals require specialist review and cross-team discussion.
+  // They are not auto-actionable and surface in doctor/prelude as informational gaps.
+  'team-understaffed',
+  'escalation-path-broken',
+  'team-decision-violation',
+  'cross-team-handoff-blocked',
 ]);
 
 const DENY_ACTIONS = new Set([

package/lib/oracle/read-model.mjs

@@ -9,6 +9,7 @@
  */
 
 import fs from 'node:fs';
+import { loadRegistry } from '../registry/loader.mjs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 
@@ -20,6 +21,7 @@ import { collectOrgGraph } from './org-graph.mjs';
 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 { doctorRoot } from '../config/xdg.mjs';
 
@@ -235,12 +237,6 @@ function collectStructureSprawl(projectDir) {
   }
 }
 
-const GRAPH_SEED_FILES = [
-  'registry/capabilities.json',
-  'specialists/contracts.json',
-  'lib/embedded-contract/workflow-defs.mjs',
-];
-
 // The living dependency matrix: file↔capability↔workflow↔test graph at
 // .cx/graph/. Surfaces three oversight signals — staleness (seeds changed
 // since last build), coverage (capabilities/workflows with no impl or test
@@ -314,6 +310,105 @@ function collectDeadCodeSync(rootDir, projectDir) {
   return { present: false, pendingAsync: true, deadCount: 0, regressions: [] };
 }
 
+function specialistTeamId(specialist) {
+  return specialist.teamId ?? specialist.team ?? null;
+}
+
+function specialistsForTeamEntity(teamId, team, registry) {
+  const all = Object.values(registry.specialists ?? {});
+  if (team.kind === 'group' && Array.isArray(team.squads) && team.squads.length > 0) {
+    const squadIds = new Set(team.squads);
+    return all.filter((s) => squadIds.has(specialistTeamId(s)));
+  }
+  return all.filter((s) => specialistTeamId(s) === teamId);
+}
+
+function isTeamStaffed(teamId, team, registry) {
+  if (specialistsForTeamEntity(teamId, team, registry).length > 0) return true;
+  if (team.kind === 'squad' && Array.isArray(team.specialists) && team.specialists.length > 0) {
+    return true;
+  }
+  return false;
+}
+
+function ownerExistsForTeam(teamId, team, registry) {
+  const ownerRole = team.owner;
+  if (!ownerRole) return true;
+  return specialistsForTeamEntity(teamId, team, registry).some((s) => s.role === ownerRole);
+}
+
+function collectTeamGovernance(rootDir) {
+  const registry = loadRegistry({ rootDir });
+  if (!registry?.teams) {
+    return { present: false, teams: {} };
+  }
+
+  const teams = {};
+  for (const [teamId, team] of Object.entries(registry.teams)) {
+    const roles = team.roles ?? [];
+    const escalationPath = team.escalationPath ?? [];
+    const decisionRights = team.decisionRights ?? [];
+    const forbiddenDecisions = team.forbiddenDecisions ?? [];
+    const teamSpecialists = specialistsForTeamEntity(teamId, team, registry);
+
+    // Check if escalation path is complete (all roles exist in registry)
+    const escalationPathBroken = escalationPath.some((role) => {
+      const specialist = Object.values(registry.specialists ?? {}).some((s) => s.role === role);
+      return !specialist;
+    });
+
+    teams[teamId] = {
+      id: teamId,
+      name: team.name,
+      kind: team.kind ?? null,
+      owner: team.owner,
+      roleCount: roles.length,
+      specialistCount: teamSpecialists.length,
+      decisionRightsCount: decisionRights.length,
+      forbiddenDecisionsCount: forbiddenDecisions.length,
+      escalationPathLength: escalationPath.length,
+      escalationPathBroken,
+      ownerExists: ownerExistsForTeam(teamId, team, registry),
+      understaffed: roles.length > 0 && !isTeamStaffed(teamId, team, registry),
+    };
+  }
+
+  // Cross-team handoff health: a crossing contract whose required approver team
+  // is missing or unstaffed can never be approved, so the handoff is blocked.
+  const contracts = Array.isArray(registry.contracts)
+    ? registry.contracts
+    : Object.values(registry.contracts ?? {});
+  const crossTeamHandoffsBlocked = [];
+  for (const contract of contracts) {
+    const boundary = contract.teamBoundary;
+    if (!boundary?.crosses
+      || !Array.isArray(boundary.requiresApprovalFrom)
+      || boundary.requiresApprovalFrom.length === 0) {
+      continue;
+    }
+    const unstaffedApprovers = boundary.requiresApprovalFrom.filter((approverId) => {
+      const team = registry.teams?.[approverId];
+      if (!team) return true;
+      return !isTeamStaffed(approverId, team, registry);
+    });
+    if (unstaffedApprovers.length > 0) {
+      crossTeamHandoffsBlocked.push({
+        contract: contract.id,
+        producerTeam: boundary.producerTeam ?? null,
+        consumerTeam: boundary.consumerTeam ?? null,
+        blockedBy: unstaffedApprovers,
+      });
+    }
+  }
+
+  return {
+    present: true,
+    teamCount: Object.keys(teams).length,
+    teams,
+    crossTeamHandoffsBlocked,
+  };
+}
+
 /**
  * Collect the Oracle read model from durable Construct signals.
  *
@@ -334,6 +429,7 @@ export function collectReadModel({ rootDir, projectDir, homeDir }) {
   const registryValidate = collectRegistryValidate(rootDir);
   const orgGraph = collectOrgGraph({ rootDir, projectDir, parity, registryValidate });
   const artifactGate = collectArtifactGateSignals({ rootDir, projectDir });
+  const teamGovernance = collectTeamGovernance(rootDir);
 
   return {
     collectedAt,
@@ -349,6 +445,7 @@ export function collectReadModel({ rootDir, projectDir, homeDir }) {
     parity,
     orgGraph,
     artifactGate,
+    teamGovernance,
     beads: collectBeadsOpenCount(projectDir),
     hookFailures: collectHookFailures(homeDir),
     structure: collectStructureSprawl(projectDir),