@geraldmaron/construct 1.2.2 → 1.3.0

package/lib/registry/validator.mjs

@@ -0,0 +1,438 @@
+/**
+ * lib/registry/validator.mjs — Validates unified registry invariants.
+ *
+ * Enforces 13 invariants that guarantee the registry is internally consistent:
+ * teams have owners, specialists have teams, no cycles, decisions are covered by
+ * policies, contracts reference valid parties, and escalation paths are sound.
+ *
+ * Export: validate(registry, opts) → { ok, errors, warnings }
+ * Each error/warning has { id, severity, message, location }
+ */
+
+/**
+ * Validate a unified registry against all invariants.
+ * @param {object} registry - The unified registry object
+ * @param {object} opts - Options (reserved for future use)
+ * @returns {{ ok: boolean, errors: Array, warnings: Array }}
+ */
+export function validate(registry, opts = {}) {
+  const errors = [];
+  const warnings = [];
+
+  if (!registry || typeof registry !== 'object') {
+    return {
+      ok: false,
+      errors: [{ id: 'invalid-input', severity: 'error', message: 'Registry must be a non-null object', location: '#' }],
+      warnings: [],
+    };
+  }
+
+  // Schema compliance must pass before graph traversal; structural errors short-circuit.
+
+  const schemaCheck = checkSchemaCompliance(registry);
+  errors.push(...schemaCheck.errors);
+  warnings.push(...schemaCheck.warnings);
+  if (schemaCheck.errors.length > 0) {
+    return { ok: false, errors, warnings };
+  }
+
+  const teams = registry.teams || {};
+  const specialists = registry.specialists || {};
+  const contracts = registry.contracts || {};
+  const policies = registry.policies || {};
+
+  // Team and specialist graph: owners, membership, and naming collisions.
+
+  errors.push(...checkTeamHasOwner(teams, specialists));
+  errors.push(...checkSpecialistTeamExists(specialists, teams));
+  errors.push(...checkTeamHasSpecialists(teams, specialists));
+  errors.push(...checkNoNameCollisions(specialists));
+
+  // Policy coverage for team decision rights and forbidden actions.
+
+  warnings.push(...checkDecisionHasPolicy(teams, policies));
+  warnings.push(...checkForbiddenDecisions(teams, policies));
+
+  // Escalation paths must resolve specialists and remain acyclic.
+
+  errors.push(...checkEscalationPathValid(teams, specialists));
+  errors.push(...checkNoCircularEscalation(teams));
+
+  // Contracts and policies must reference teams and specialists that exist.
+
+  errors.push(...checkContractPartiesExist(contracts, specialists));
+  errors.push(...checkContractTeamBoundaries(contracts, teams));
+  errors.push(...checkPolicyTeamOwnerExists(policies, teams));
+  errors.push(...checkPolicyApproverTeamsExist(policies, teams));
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+// === Individual invariant checks ===
+
+function checkSchemaCompliance(registry) {
+  const errors = [];
+  const warnings = [];
+
+  if (registry.version !== 2 && registry.version !== 3) {
+    errors.push({
+      id: 'invalid-version',
+      severity: 'error',
+      message: `Schema version must be 2 or 3, got ${registry.version}`,
+      location: '#/version',
+    });
+  }
+
+  if (typeof registry.teams !== 'object' || registry.teams === null) {
+    errors.push({
+      id: 'missing-teams',
+      severity: 'error',
+      message: 'teams must be an object',
+      location: '#/teams',
+    });
+  }
+
+  if (typeof registry.specialists !== 'object' || registry.specialists === null) {
+    errors.push({
+      id: 'missing-specialists',
+      severity: 'error',
+      message: 'specialists must be an object',
+      location: '#/specialists',
+    });
+  }
+
+  if (typeof registry.contracts !== 'object' || registry.contracts === null) {
+    errors.push({
+      id: 'missing-contracts',
+      severity: 'error',
+      message: 'contracts must be an object',
+      location: '#/contracts',
+    });
+  }
+
+  if (typeof registry.policies !== 'object' || registry.policies === null) {
+    errors.push({
+      id: 'missing-policies',
+      severity: 'error',
+      message: 'policies must be an object',
+      location: '#/policies',
+    });
+  }
+
+  return { errors, warnings };
+}
+
+function isGroup(team) {
+  return team?.kind === 'group';
+}
+
+function checkTeamHasOwner(teams, specialists) {
+  const errors = [];
+
+  for (const [teamId, team] of Object.entries(teams)) {
+    if (isGroup(team)) continue;
+
+    const ownerRole = team.owner;
+    if (!ownerRole) {
+      errors.push({
+        id: 'team-missing-owner',
+        severity: 'error',
+        message: `Team ${teamId} missing owner field`,
+        location: `#/teams/${teamId}/owner`,
+      });
+      continue;
+    }
+
+    const hasOwner = Object.values(specialists).some(
+      (spec) => spec.team === teamId && (spec.role === 'owner' || spec.role === ownerRole),
+    );
+
+    if (!hasOwner) {
+      errors.push({
+        id: 'team-no-owner-specialist',
+        severity: 'error',
+        message: `Team ${teamId} has owner role ${ownerRole} but no specialist with that role assigned`,
+        location: `#/teams/${teamId}`,
+      });
+    }
+  }
+
+  return errors;
+}
+
+function checkSpecialistTeamExists(specialists, teams) {
+  const errors = [];
+  const teamIds = Object.keys(teams);
+
+  for (const [specId, spec] of Object.entries(specialists)) {
+    if (!spec.team) {
+      errors.push({
+        id: 'specialist-missing-team',
+        severity: 'error',
+        message: `Specialist ${specId} missing team assignment`,
+        location: `#/specialists/${specId}/team`,
+      });
+    } else if (!teamIds.includes(spec.team) && spec.team !== 'unknown') {
+      errors.push({
+        id: 'specialist-unknown-team',
+        severity: 'error',
+        message: `Specialist ${specId} references unknown team ${spec.team}`,
+        location: `#/specialists/${specId}/team`,
+      });
+    }
+  }
+
+  return errors;
+}
+
+function checkTeamHasSpecialists(teams, specialists) {
+  const errors = [];
+  const specsByTeam = {};
+
+  for (const spec of Object.values(specialists)) {
+    if (spec.team) {
+      if (!specsByTeam[spec.team]) specsByTeam[spec.team] = [];
+      specsByTeam[spec.team].push(spec);
+    }
+  }
+
+  for (const teamId of Object.keys(teams)) {
+    const team = teams[teamId];
+    if (isGroup(team)) continue;
+
+    if (!specsByTeam[teamId] || specsByTeam[teamId].length === 0) {
+      errors.push({
+        id: 'team-no-specialists',
+        severity: 'error',
+        message: `Team ${teamId} has no assigned specialists`,
+        location: `#/teams/${teamId}`,
+      });
+    }
+  }
+
+  return errors;
+}
+
+function checkNoNameCollisions(specialists) {
+  const errors = [];
+  const seen = new Map();
+
+  for (const [specId, spec] of Object.entries(specialists)) {
+    if (seen.has(spec.name)) {
+      errors.push({
+        id: 'specialist-name-collision',
+        severity: 'error',
+        message: `Specialist name collision: ${spec.name} appears in ${seen.get(spec.name)} and ${specId}`,
+        location: `#/specialists/${specId}/name`,
+      });
+    }
+    seen.set(spec.name, specId);
+  }
+
+  return errors;
+}
+
+function checkDecisionHasPolicy(teams, policies) {
+  const warnings = [];
+  const policyIds = Object.keys(policies);
+
+  for (const [teamId, team] of Object.entries(teams)) {
+    const rights = team.decisionRights || [];
+    for (const right of rights) {
+      if (!policyIds.includes(right)) {
+        warnings.push({
+          id: 'decision-no-policy',
+          severity: 'warning',
+          message: `Team ${teamId} claims decision right ${right} but no policy with that id exists`,
+          location: `#/teams/${teamId}/decisionRights`,
+        });
+      }
+    }
+  }
+
+  return warnings;
+}
+
+function checkForbiddenDecisions(teams, policies) {
+  const warnings = [];
+
+  for (const [teamId, team] of Object.entries(teams)) {
+    const forbidden = team.forbiddenDecisions || [];
+    for (const decision of forbidden) {
+      if (!(decision in policies)) {
+        warnings.push({
+          id: 'forbidden-decision-invalid',
+          severity: 'warning',
+          message: `Team ${teamId} forbids decision ${decision} but it is not a recognized decision`,
+          location: `#/teams/${teamId}/forbiddenDecisions`,
+        });
+      }
+    }
+  }
+
+  return warnings;
+}
+
+function checkEscalationPathValid(teams, specialists) {
+   const errors = [];
+   
+   // Build a set of all valid roles (from all teams)
+   const allRoles = new Set();
+   for (const team of Object.values(teams)) {
+     for (const role of team.roles || []) {
+       allRoles.add(role);
+     }
+   }
+
+   for (const [teamId, team] of Object.entries(teams)) {
+     const path = team.escalationPath || [];
+     for (let i = 0; i < path.length; i++) {
+       const role = path[i];
+       if (role === 'orchestrator') continue; // orchestrator is always valid
+
+       // Check if this role exists in any team's roles
+       if (!allRoles.has(role)) {
+         errors.push({
+           id: 'escalation-path-invalid-role',
+           severity: 'error',
+           message: `Team ${teamId} escalation path references role ${role} at index ${i} with no team claiming that role`,
+           location: `#/teams/${teamId}/escalationPath/${i}`,
+         });
+       }
+     }
+   }
+
+   return errors;
+ }
+
+function checkNoCircularEscalation(teams) {
+  const errors = [];
+
+  for (const [teamId, team] of Object.entries(teams)) {
+    const path = team.escalationPath || [];
+    const visited = new Set();
+
+    for (const role of path) {
+      if (visited.has(role)) {
+        errors.push({
+          id: 'circular-escalation',
+          severity: 'error',
+          message: `Team ${teamId} escalation path contains cycle: ${role} appears twice`,
+          location: `#/teams/${teamId}/escalationPath`,
+        });
+        break;
+      }
+      visited.add(role);
+    }
+  }
+
+  return errors;
+}
+
+function checkContractPartiesExist(contracts, specialists) {
+   const errors = [];
+   const specialistIds = new Set(Object.keys(specialists));
+   const validParties = new Set(['user', 'construct', '*', ...specialistIds]); // * = wildcard producer
+
+   for (const [contractId, contract] of Object.entries(contracts)) {
+     if (!validParties.has(contract.producer)) {
+       errors.push({
+         id: 'contract-unknown-producer',
+         severity: 'error',
+         message: `Contract ${contractId} references unknown producer ${contract.producer}`,
+         location: `#/contracts/${contractId}/producer`,
+       });
+     }
+
+     if (!validParties.has(contract.consumer)) {
+       errors.push({
+         id: 'contract-unknown-consumer',
+         severity: 'error',
+         message: `Contract ${contractId} references unknown consumer ${contract.consumer}`,
+         location: `#/contracts/${contractId}/consumer`,
+       });
+     }
+   }
+
+   return errors;
+ }
+
+function checkContractTeamBoundaries(contracts, teams) {
+  const errors = [];
+  const teamIds = Object.keys(teams);
+
+  for (const [contractId, contract] of Object.entries(contracts)) {
+    if (contract.teamBoundary) {
+      const { producerTeam, consumerTeam } = contract.teamBoundary;
+
+      if (producerTeam && !teamIds.includes(producerTeam)) {
+        errors.push({
+          id: 'contract-unknown-team',
+          severity: 'error',
+          message: `Contract ${contractId} teamBoundary references unknown team ${producerTeam}`,
+          location: `#/contracts/${contractId}/teamBoundary/producerTeam`,
+        });
+      }
+
+      if (consumerTeam && !teamIds.includes(consumerTeam)) {
+        errors.push({
+          id: 'contract-unknown-team',
+          severity: 'error',
+          message: `Contract ${contractId} teamBoundary references unknown team ${consumerTeam}`,
+          location: `#/contracts/${contractId}/teamBoundary/consumerTeam`,
+        });
+      }
+    }
+  }
+
+  return errors;
+}
+
+function checkPolicyTeamOwnerExists(policies, teams) {
+  const errors = [];
+  const teamIds = Object.keys(teams);
+
+  for (const [policyId, policy] of Object.entries(policies)) {
+    if (policy.owner && !teamIds.includes(policy.owner) && policy.owner !== 'orchestrator') {
+      errors.push({
+        id: 'policy-unknown-owner',
+        severity: 'error',
+        message: `Policy ${policyId} owner team ${policy.owner} does not exist`,
+        location: `#/policies/${policyId}/owner`,
+      });
+    }
+  }
+
+  return errors;
+}
+
+function checkPolicyApproverTeamsExist(policies, teams) {
+   const errors = [];
+   const teamIds = Object.keys(teams);
+   const policyIds = Object.keys(policies);
+
+   for (const [policyId, policy] of Object.entries(policies)) {
+     const approvers = policy.requiresApprovalFrom || [];
+     for (let i = 0; i < approvers.length; i++) {
+       const approverId = approvers[i];
+       // approvers can be team IDs or policy IDs (for nested approval requirements)
+       const isTeamId = teamIds.includes(approverId);
+       const isPolicyId = policyIds.includes(approverId);
+       
+       if (!isTeamId && !isPolicyId) {
+         errors.push({
+           id: 'policy-unknown-approver',
+           severity: 'error',
+           message: `Policy ${policyId} requiresApprovalFrom references unknown team or policy ${approverId}`,
+           location: `#/policies/${policyId}/requiresApprovalFrom/${i}`,
+         });
+       }
+     }
+   }
+
+   return errors;
+ }

package/lib/research-execution-policy.mjs

@@ -0,0 +1,173 @@
+/**
+ * lib/research-execution-policy.mjs — surface-agnostic research routing policy.
+ *
+ * Research is not tied to one MCP. Hosts can have Context7, plain web search,
+ * attached files, or only repo access. This module returns the same evidence
+ * ladder to every surface so research remains useful inside a project, outside a
+ * project, or in a mixed conversation that turns into artifact drafting.
+ */
+
+const LIBRARY_DOC_PATTERNS = [
+  /\b(api|sdk|framework|library|package|module|cli|tooling?)\b/i,
+  /\bdocs?|documentation|reference|changelog|release notes?|migration guide\b/i,
+  /\breact|next\.?js|node\.?js|typescript|python|go|rust|java|spring|django|rails|tailwind|prisma|aws|gcp|azure|kubernetes|terraform\b/i,
+];
+
+const SECURITY_PATTERNS = [
+  /\bcve\b/i,
+  /\bvulnerabilit(?:y|ies)\b/i,
+  /\badvisory|exploit|cwe|cvss|owasp|supply chain\b/i,
+];
+
+const LITERATURE_PATTERNS = [
+  /\bpaper|study|benchmark|arxiv|anthology|proceedings|dataset|experiment|literature\b/i,
+];
+
+const MARKET_PATTERNS = [
+  /\bmarket|pricing|adoption|competition|competitive|vendor|arr|revenue|survey|share\b/i,
+];
+
+const REGULATORY_PATTERNS = [
+  /\bregulation|regulatory|compliance|standard|policy|law|gdpr|hipaa|soc 2|iso 27001|fedramp\b/i,
+];
+
+const REPO_PATTERNS = [
+  /\bthis (repo|repository|project|codebase)\b/i,
+  /\bin this (repo|repository|project|codebase)\b/i,
+  /\bour (repo|repository|project|codebase)\b/i,
+  /\bmodule\b|\bfunction\b|\bimplementation\b|\bsource code\b/i,
+];
+
+const CONSTRUCT_SELF_PATTERNS = [
+  /\bconstruct\b/i,
+  /\bthis tool\b/i,
+  /\bthis system\b/i,
+  /\bthis agent\b/i,
+];
+
+export function classifyResearchDomain(request = '') {
+  const text = String(request || '');
+  if (!text.trim()) return 'general-external';
+  if (REPO_PATTERNS.some((pattern) => pattern.test(text))) return 'repo';
+  if (CONSTRUCT_SELF_PATTERNS.some((pattern) => pattern.test(text))) return 'construct-self';
+  if (SECURITY_PATTERNS.some((pattern) => pattern.test(text))) return 'security';
+  if (LITERATURE_PATTERNS.some((pattern) => pattern.test(text))) return 'literature';
+  if (MARKET_PATTERNS.some((pattern) => pattern.test(text))) return 'market';
+  if (REGULATORY_PATTERNS.some((pattern) => pattern.test(text))) return 'regulatory';
+  if (LIBRARY_DOC_PATTERNS.some((pattern) => pattern.test(text))) return 'library-docs';
+  return 'general-external';
+}
+
+function domainStartingPoints(domain) {
+  switch (domain) {
+    case 'construct-self':
+      return ['Construct knowledge base and shipped docs'];
+    case 'repo':
+      return ['repo code', 'repo tests', 'repo docs', 'attached or ingested project files'];
+    case 'library-docs':
+      return ['official versioned docs', 'official changelog', 'official migration guide', 'release notes'];
+    case 'security':
+      return ['NVD', 'GitHub Security Advisories', 'OWASP', 'vendor advisories'];
+    case 'literature':
+      return ['papers', 'conference proceedings', 'official benchmark writeups', 'dataset docs'];
+    case 'market':
+      return ['company announcements', 'SEC filings', 'official pricing/docs', 'named primary-source reporting'];
+    case 'regulatory':
+      return ['regulation text', 'issuing authority guidance', 'official standard text'];
+    default:
+      return ['most authoritative primary source for the claim', 'official docs', 'standards', 'source code', 'first-party announcements'];
+  }
+}
+
+function externalLadder(domain) {
+  if (domain === 'construct-self') {
+    return [
+      {
+        step: 'construct-knowledge',
+        when: 'The question is about Construct itself.',
+        action: 'Use Construct knowledge and shipped docs first.',
+        preferredTools: ['knowledge_search'],
+      },
+    ];
+  }
+
+  if (domain === 'repo') {
+    return [
+      {
+        step: 'repo-evidence',
+        when: 'The question is about the current project/repo or attached materials.',
+        action: 'Read code, tests, configs, prior artifacts, and ingested files before any external search.',
+        preferredTools: ['repo file search', 'project docs', 'ingested artifact search'],
+      },
+      {
+        step: 'targeted-external',
+        when: 'Local evidence is insufficient and the question depends on an external standard or dependency.',
+        action: 'Fetch the exact external primary source that governs the claim.',
+        preferredTools: ['context7 when it is a library/API docs question', 'web search + direct fetch of official docs otherwise'],
+      },
+    ];
+  }
+
+  if (domain === 'library-docs') {
+    return [
+      {
+        step: 'context7-preferred',
+        when: 'Context7 is available and the topic is a library/framework/API/CLI/cloud-docs question.',
+        action: 'Use Context7 for current versioned documentation.',
+        preferredTools: ['context7'],
+      },
+      {
+        step: 'official-web-fallback',
+        when: 'Context7 is unavailable, incomplete, or the answer needs confirmation.',
+        action: 'Search and fetch official docs, changelogs, migration guides, and release notes directly on the web.',
+        preferredTools: ['web search', 'direct fetch/open of official docs'],
+      },
+      {
+        step: 'secondary-locator',
+        when: 'Official docs are hard to locate.',
+        action: 'Use secondary sources only to locate the primary source; do not treat them as final evidence.',
+        preferredTools: ['web search'],
+      },
+    ];
+  }
+
+  return [
+    {
+      step: 'primary-external',
+      when: 'The question concerns external facts beyond the current repo.',
+      action: 'Go directly to the domain-appropriate primary sources.',
+      preferredTools: ['web search', 'direct fetch/open of primary sources'],
+    },
+    {
+      step: 'secondary-locator',
+      when: 'Primary sources need discovery help.',
+      action: 'Use secondary/tertiary sources only to locate the primary source, then verify against the primary.',
+      preferredTools: ['web search'],
+    },
+  ];
+}
+
+export function buildResearchExecutionPolicy({ request = '' } = {}) {
+  const domain = classifyResearchDomain(request);
+  return {
+    mode: 'evidence-first',
+    supportsGeneralConversation: true,
+    canResearchInsideOrOutsideProject: true,
+    domain,
+    internalFirst: [
+      'user-supplied files and links',
+      'current repo code, docs, tests, and configs when relevant',
+      'prior project research and ingested knowledge when relevant',
+    ],
+    startingPoints: domainStartingPoints(domain),
+    toolRouting: externalLadder(domain),
+    sourceRules: [
+      'Prefer primary sources for load-bearing claims.',
+      'Use Context7 only for library/framework/API/cloud docs when available.',
+      'Fall back to web search plus direct fetch of official docs when Context7 is absent or insufficient.',
+      'For non-docs research, use domain-appropriate primary sources rather than a generic docs MCP.',
+      'Community/blog/forum content may help locate sources or capture sentiment, but not replace primary evidence for factual claims.',
+    ],
+    recencyRule: 'Search most-recent-first. For fast-moving topics, treat sources older than 12 months as stale until reconfirmed.',
+  };
+}

package/lib/roles/catalog.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/roles/catalog.mjs — role listing and display helpers.
  *
- * Reads the flat `specialists` array in specialists/registry.json to produce the
+ * Reads the flat `specialists` array in specialists/org to produce the
  * list of available roles. Each descriptor carries the registry-prefixed display
  * name (cx-<name>), description, model tier, edit capability, and skill ids — the
  * shape consumed by the `roles:list` CLI command and the embedded capability
@@ -12,18 +12,13 @@
  * the flat list only and never invents grouping that has no source.
  */
 
-import { readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const REGISTRY_PATH = join(__dirname, '..', '..', 'specialists', 'registry.json');
+import { loadRegistry as loadAssembledRegistry } from '../registry/loader.mjs';
 
 let cached = null;
 
 function loadRegistry() {
   if (cached) return cached;
-  cached = JSON.parse(readFileSync(REGISTRY_PATH, 'utf8'));
+  cached = loadAssembledRegistry();
   return cached;
 }
 
@@ -35,7 +30,7 @@ function loadRegistry() {
 export function listRoles() {
   const registry = loadRegistry();
   const prefix = registry.prefix || 'cx';
-  const specialists = Array.isArray(registry.specialists) ? registry.specialists : [];
+  const specialists = Object.values(registry.specialists || {});
 
   return specialists.map((s) => ({
     id: s.name,