@geraldmaron/construct 1.2.2 → 1.3.0

package/lib/oracle/reconcile.mjs

@@ -93,6 +93,20 @@ function pruneRaisedIssues(projectDir, { dryRun = false } = {}) {
 
 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) =>
@@ -107,6 +121,19 @@ function isBareGoalConstructViolation(row) {
   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 }}
@@ -116,18 +143,18 @@ export function planContractViolationSupersede(projectDir) {
   if (!recent.length) {
     return { shouldSupersede: false, recentCount: 0, reason: 'no recent contract violations' };
   }
-  const allBareGoal = recent.every(isBareGoalConstructViolation);
-  if (!allBareGoal) {
+  const allDevSessionNoise = recent.every(isDevSessionContractNoise);
+  if (!allDevSessionNoise) {
     return {
       shouldSupersede: false,
       recentCount: recent.length,
-      reason: 'recent violations include non-bare-goal construct-to-orchestrator or other contracts',
+      reason: 'recent violations include non-probe contract failures',
     };
   }
   return {
     shouldSupersede: true,
     recentCount: recent.length,
-    reason: 'historical bare-goal construct-to-orchestrator violations superseded after handoff enrichment fix',
+    reason: 'dev-session contract probes superseded (bare-goal construct, empty researcher/a11y packets)',
   };
 }
 

package/lib/oracle/remediation-dispatch.mjs

@@ -0,0 +1,53 @@
+/**
+ * lib/oracle/remediation-dispatch.mjs — static vs swarm dispatch for Oracle remediation.
+ *
+ * Seeds orchestration-policy teamRouting with gap/action remediation specialists.
+ * Swarm when involvedTeams.length > 1; static when a single team owns the work.
+ */
+
+import { classifyIntent, teamRoutingForSpecialists } from '../orchestration-policy.mjs';
+import { routeGap, routeAction } from './routing.mjs';
+
+function remediationText(item) {
+  return String(item.detail ?? item.summary ?? item.id ?? 'Oracle remediation');
+}
+
+function seededSpecialists(item) {
+  const route = item.remediationRoute ?? (item.kind ? routeAction(item.kind) : routeGap(item));
+  return [route.primary, route.secondary].filter(Boolean);
+}
+
+/**
+ * @param {object} item — gap or recommended action with optional remediationRoute
+ * @param {{ projectDir?: string, cwd?: string }} [opts]
+ * @returns {{ mode: 'static'|'swarm', primary: string, specialists: string[], teamRouting: object }}
+ */
+export function resolveRemediationDispatch(item, { projectDir, cwd } = {}) {
+  const route = item.remediationRoute ?? (item.kind ? routeAction(item.kind) : routeGap(item));
+  const primary = route.primary;
+  const specialists = seededSpecialists(item);
+  const request = remediationText(item);
+  const intent = classifyIntent(request);
+  const teamRouting = teamRoutingForSpecialists(specialists, {
+    intent,
+    request,
+    cwd: cwd ?? projectDir ?? null,
+  });
+
+  const involvedTeams = teamRouting.involvedTeams ?? [];
+  if (involvedTeams.length <= 1) {
+    return {
+      mode: 'static',
+      primary,
+      specialists: [primary],
+      teamRouting,
+    };
+  }
+
+  return {
+    mode: 'swarm',
+    primary,
+    specialists: Array.from(new Set(specialists)),
+    teamRouting,
+  };
+}

package/lib/oracle/routing.mjs

@@ -34,6 +34,11 @@ const GAP_ROUTES = {
   'dependency-graph-stale': { primary: 'cx-platform-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 },
 };
 
 const ACTION_ROUTES = {

package/lib/oracle/synthesize.mjs

@@ -5,6 +5,8 @@
 
 import { orgGraphToGapHints } from './org-graph.mjs';
 import { routeAction, routeGap, signOffMetadata } from './routing.mjs';
+import { resolveRemediationDispatch } from './remediation-dispatch.mjs';
+import { isConstructPackageRepo } from '../host-disposition.mjs';
 
 const LOW_SUCCESS_RATE = 0.6;
 
@@ -224,7 +226,8 @@ export function synthesizeVerdict(readModel) {
   }
 
   const dupLanes = readModel.structure?.duplicateLanes ?? [];
-  if (dupLanes.length > 0) {
+  const skipStructureSprawl = isConstructPackageRepo(readModel.projectDir);
+  if (dupLanes.length > 0 && !skipStructureSprawl) {
     gaps.push(gap(
       'structure-sprawl',
       'medium',
@@ -259,11 +262,13 @@ export function synthesizeVerdict(readModel) {
 
   const artifactGate = readModel.artifactGate ?? {};
   if (artifactGate.specialistAudit?.present && !artifactGate.specialistAudit.pass) {
+    const auditDetail = artifactGate.specialistAudit.error
+      ?? `${artifactGate.specialistAudit.crossCheckCount} issue(s)`;
     gaps.push(gap(
       'specialist-audit-drift',
       'high',
       'artifact-manifest',
-      `Specialist audit cross-check failed (${artifactGate.specialistAudit.crossCheckCount} issue(s))`,
+      `Specialist audit cross-check failed (${auditDetail})`,
     ));
     recommendedActions.push(action(
       'registry-validate',
@@ -285,7 +290,7 @@ export function synthesizeVerdict(readModel) {
     ));
   }
 
-  if ((artifactGate.reviewerGapCount ?? 0) > 0) {
+  if ((artifactGate.reviewerGapCount ?? 0) > 0 && artifactGate.reviewerGateArmed !== false) {
     gaps.push(gap(
       'artifact-reviewer-gap',
       'medium',
@@ -340,6 +345,70 @@ export function synthesizeVerdict(readModel) {
     }
   }
 
+  // Team governance signals from unified registry
+  const teamGov = readModel.teamGovernance ?? { present: false, teams: {} };
+  if (teamGov.present) {
+    const understaffedTeams = Object.values(teamGov.teams ?? {}).filter((t) => t.understaffed);
+    if (understaffedTeams.length > 0) {
+      gaps.push(gap(
+        'team-understaffed',
+        'high',
+        'team-governance',
+        `${understaffedTeams.length} team(s) understaffed: ${understaffedTeams.map((t) => t.id).join(', ')}`,
+      ));
+      recommendedActions.push(action(
+        'specialist-review',
+        'Review team staffing gaps and escalate to rd-lead for resolution',
+        { teams: understaffedTeams.map((t) => ({ id: t.id, name: t.name })) },
+      ));
+    }
+
+    const brokenEscalations = Object.values(teamGov.teams ?? {}).filter((t) => t.escalationPathBroken);
+    if (brokenEscalations.length > 0) {
+      gaps.push(gap(
+        'escalation-path-broken',
+        'high',
+        'team-governance',
+        `${brokenEscalations.length} team(s) have broken escalation path: ${brokenEscalations.map((t) => t.id).join(', ')}`,
+      ));
+      recommendedActions.push(action(
+        'registry-validate',
+        'Validate and repair team escalation paths in unified registry',
+        { teams: brokenEscalations.map((t) => t.id) },
+      ));
+    }
+
+    const ownerlessTeams = Object.values(teamGov.teams ?? {}).filter((t) => !t.ownerExists);
+    if (ownerlessTeams.length > 0) {
+      gaps.push(gap(
+        'team-decision-violation',
+        'high',
+        'team-governance',
+        `${ownerlessTeams.length} team(s) missing owner specialist: ${ownerlessTeams.map((t) => `${t.id} (owner: ${t.owner})`).join(', ')}`,
+      ));
+      recommendedActions.push(action(
+        'specialist-review',
+        'Assign specialists to team owner roles or update registry',
+        { teams: ownerlessTeams.map((t) => ({ id: t.id, missingOwner: t.owner })) },
+      ));
+    }
+
+    const blockedHandoffs = teamGov.crossTeamHandoffsBlocked ?? [];
+    if (blockedHandoffs.length > 0) {
+      gaps.push(gap(
+        'cross-team-handoff-blocked',
+        'high',
+        'team-governance',
+        `${blockedHandoffs.length} cross-team handoff(s) blocked on an unstaffed approver team: ${blockedHandoffs.map((h) => `${h.contract} (needs ${h.blockedBy.join(', ')})`).join('; ')}`,
+      ));
+      recommendedActions.push(action(
+        'specialist-review',
+        'Staff the required approver team(s) or relax the cross-team approval requirement so the handoff can complete',
+        { handoffs: blockedHandoffs },
+      ));
+    }
+  }
+
   for (const hint of orgGraphToGapHints(readModel.orgGraph ?? {})) {
     if (!gaps.some((g) => g.id === hint.id)) gaps.push(hint);
     if (hint.id === 'workflow-misaligned') {
@@ -365,6 +434,10 @@ export function synthesizeVerdict(readModel) {
       secondary: route.secondary ?? null,
       gateType: route.gateType ?? null,
     };
+    const dispatch = resolveRemediationDispatch(g, { projectDir: readModel.projectDir });
+    g.remediationRoute.mode = dispatch.mode;
+    g.remediationRoute.specialists = dispatch.specialists;
+    g.remediationRoute.teamRouting = dispatch.teamRouting;
   }
   for (const a of recommendedActions) {
     const route = routeAction(a.kind);
@@ -372,6 +445,10 @@ export function synthesizeVerdict(readModel) {
       primary: route.primary,
       gateType: route.gateType ?? null,
     };
+    const dispatch = resolveRemediationDispatch(a, { projectDir: readModel.projectDir });
+    a.remediationRoute.mode = dispatch.mode;
+    a.remediationRoute.specialists = dispatch.specialists;
+    a.remediationRoute.teamRouting = dispatch.teamRouting;
   }
 
   let verdict = 'healthy';

package/lib/orchestration/routing-tables.mjs

@@ -2,7 +2,7 @@
  * lib/orchestration/routing-tables.mjs — declarative routing resolver.
  *
  * Reads specialist subscriptions, doc-artifact ownership, and watch-condition
- * references from specialists/registry.json (with optional .cx/specialists/
+ * references from specialists/org (with optional .cx/specialists/
  * overlays) and exposes the forward lookups the orchestration layer needs.
  *
  * The resolver is the single source of truth for event/doc/watch routing.
@@ -19,10 +19,8 @@
 
 import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { findProjectRoot } from '../project-root.mjs';
-
-const REGISTRY_PATH = fileURLToPath(new URL('../../specialists/registry.json', import.meta.url));
+import { loadRegistry, clearCache } from '../registry/loader.mjs';
 
 // Watch-condition predicates. Each is a pure function from requestSignals
 // (see orchestration-policy.requestSignals) to boolean. Registry entries
@@ -65,9 +63,10 @@ function loadOverlays() {
 }
 
 function buildTables() {
-  const registry = readJsonSafe(REGISTRY_PATH);
-  if (!registry || !Array.isArray(registry.specialists)) {
-    throw new Error('routing-tables: registry.json missing or malformed');
+  clearCache();
+  const registry = loadRegistry();
+  if (!registry || typeof registry.specialists !== 'object') {
+    throw new Error('routing-tables: assembled registry missing or malformed');
   }
 
   // Forward maps. Last writer wins for overlays; the resolver validates
@@ -83,8 +82,8 @@ function buildTables() {
 
   function apply(entry, source) {
     const cxId = entry.name?.startsWith('cx-') ? entry.name : `cx-${entry.name}`;
-    if (Array.isArray(entry.subscriptions)) {
-      for (const event of entry.subscriptions) {
+    if (Array.isArray(entry.events || entry.subscriptions)) {
+      for (const event of (entry.events || entry.subscriptions)) {
         if (eventToOwner.has(event) && eventToOwner.get(event) !== cxId && source === 'registry') {
           errors.push(`duplicate event ownership: ${event} → ${eventToOwner.get(event)} vs ${cxId}`);
         }
@@ -113,7 +112,7 @@ function buildTables() {
     }
   }
 
-  for (const entry of registry.specialists) apply(entry, 'registry');
+  for (const entry of Object.values(registry.specialists)) apply(entry, 'registry');
   for (const overlay of loadOverlays()) apply(overlay, 'overlay');
 
   if (errors.length > 0) {
@@ -171,6 +170,41 @@ export function knownWatchers() {
   return Object.keys(WATCHERS);
 }
 
+/**
+ * Get the team id for a specialist.
+ * Returns the team id or null if specialist not found.
+ */
+export function teamForSpecialist(specialistId) {
+  if (!specialistId) return null;
+  const registry = loadRegistry();
+  if (!registry?.specialists) return null;
+  const cxId = specialistId.startsWith('cx-') ? specialistId : `cx-${specialistId}`;
+  return registry.specialists[cxId]?.team || null;
+}
+
+/**
+ * Get all specialists in a team.
+ * Returns array of specialist ids (with cx- prefix).
+ */
+export function specialistsInTeam(teamId) {
+  if (!teamId) return [];
+  const registry = loadRegistry();
+  if (!registry?.specialists) return [];
+  return Object.entries(registry.specialists)
+    .filter(([, s]) => s.team === teamId)
+    .map(([id]) => id);
+}
+
+/**
+ * Get team definition by id.
+ * Returns team object or null if not found.
+ */
+export function getTeamById(teamId) {
+  if (!teamId) return null;
+  const registry = loadRegistry();
+  return registry?.teams?.[teamId] || null;
+}
+
 export function _resetCache() {
   cache = null;
 }

package/lib/orchestration/runtime.mjs

@@ -185,6 +185,8 @@ export async function planRun(request = {}, { env = process.env, cwd = process.c
       intent: route.intent,
       track: route.track,
       specialists: route.specialists || [],
+      suggestedWorkflowType: route.suggestedWorkflowType || null,
+      researchExecutionPolicy: route.researchExecutionPolicy || null,
       dispatchPlan: route.dispatchPlan,
       contractChain: (route.contractChain || []).map((e) => ({ id: e.contract?.id, producer: e.contract?.producer, consumer: e.contract?.consumer, stage: e.stage })),
     },

package/lib/orchestration/worker.mjs

@@ -95,7 +95,7 @@ function anthropicThinkingConfig(model) {
 
 // Key resolution delegates to the shared secret resolver so env, the dotenv
 // files, shell rc exports, and 1Password op:// references all behave identically
-// across the worker, the chat engine, and the router. allowAmbient stays the
+// across the worker and router. allowAmbient stays the
 // hermetic switch: a caller that injects its own env (embedded callers, tests)
 // suppresses file/rc discovery so a developer's real key never bleeds into a run.