@geraldmaron/construct 1.2.2 → 1.3.0

package/lib/config/legacy-config-migration.mjs

@@ -0,0 +1,125 @@
+/**
+ * lib/config/legacy-config-migration.mjs — one-time forward migration from the
+ * pre-XDG ~/.construct/config.env into the active XDG config dir.
+ *
+ * Model tier overrides and credential pointers/keys stranded by the clean break
+ * (ADR-0045) are mirrored forward without overwriting values already in XDG.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { parseEnvFile, writeEnvValues } from '../env-config.mjs';
+import { API_KEY_CREDENTIALS } from '../providers/credential-catalog.mjs';
+import { configDir } from './xdg.mjs';
+
+const MIGRATABLE_MODEL_KEY = /^(?:CX|CONSTRUCT)_MODEL_[A-Z0-9_]+$/;
+const MIGRATABLE_POINTER_KEYS = new Set(['CONSTRUCT_OP_ENV_FILE']);
+const CREDENTIAL_ENV_KEYS = new Set(
+  API_KEY_CREDENTIALS.flatMap((entry) => entry.envVars),
+);
+
+export function legacyConfigPath(homeDir = os.homedir()) {
+  return path.join(homeDir, '.construct', 'config.env');
+}
+
+function xdgConfigPath(homeDir, env) {
+  return path.join(configDir(homeDir, env), 'config.env');
+}
+
+function expandHomePath(file, home) {
+  if (file === '~') return home;
+  if (file.startsWith('~/')) return `${home}${file.slice(1)}`;
+  return file;
+}
+
+function migrateKeysFromLegacy({ legacyEnv, xdgEnv, keyFilter }) {
+  const migrated = {};
+  for (const [key, value] of Object.entries(legacyEnv)) {
+    if (!keyFilter(key)) continue;
+    if (value === '' || value === undefined) continue;
+    if (xdgEnv[key] !== undefined && xdgEnv[key] !== '') continue;
+    migrated[key] = value;
+  }
+  return migrated;
+}
+
+function backfillFromOpEnvCatalog({ migrated, xdgEnv, homeDir }) {
+  const pointer = migrated.CONSTRUCT_OP_ENV_FILE
+    || xdgEnv.CONSTRUCT_OP_ENV_FILE
+    || legacyEnvPointer(homeDir);
+  if (!pointer) return migrated;
+
+  const catalogPath = expandHomePath(pointer.replace(/^["']|["']$/g, ''), homeDir);
+  if (!fs.existsSync(catalogPath)) return migrated;
+
+  const catalog = parseEnvFile(catalogPath);
+  const next = { ...migrated };
+  for (const key of CREDENTIAL_ENV_KEYS) {
+    if (xdgEnv[key] || next[key]) continue;
+    if (!catalog[key]) continue;
+    next[key] = catalog[key];
+  }
+  return next;
+}
+
+function legacyEnvPointer(homeDir) {
+  const legacy = parseEnvFile(legacyConfigPath(homeDir));
+  return legacy.CONSTRUCT_OP_ENV_FILE || null;
+}
+
+/**
+ * Migrate stranded CX_MODEL_ and CONSTRUCT_MODEL_ tier overrides from legacy
+ * config into XDG config.env.
+ */
+export function migrateLegacyModelConfig({ homeDir = os.homedir(), env = process.env } = {}) {
+  const legacyPath = legacyConfigPath(homeDir);
+  const xdgPath = xdgConfigPath(homeDir, env);
+  const result = { performed: false, migrated: {}, legacyPath, xdgPath };
+
+  if (legacyPath === xdgPath || !fs.existsSync(legacyPath)) return result;
+
+  const legacyEnv = parseEnvFile(legacyPath);
+  const xdgEnv = parseEnvFile(xdgPath);
+  const migrated = migrateKeysFromLegacy({
+    legacyEnv,
+    xdgEnv,
+    keyFilter: (key) => MIGRATABLE_MODEL_KEY.test(key),
+  });
+
+  if (Object.keys(migrated).length === 0) return result;
+
+  writeEnvValues(xdgPath, migrated);
+  result.performed = true;
+  result.migrated = migrated;
+  return result;
+}
+
+/**
+ * Migrate CONSTRUCT_OP_ENV_FILE and API-key env vars from legacy config, then
+ * backfill any still-missing credential keys from the referenced op-run catalog.
+ */
+export function migrateLegacyCredentialConfig({ homeDir = os.homedir(), env = process.env } = {}) {
+  const legacyPath = legacyConfigPath(homeDir);
+  const xdgPath = xdgConfigPath(homeDir, env);
+  const result = { performed: false, migrated: {}, legacyPath, xdgPath };
+
+  if (legacyPath === xdgPath || !fs.existsSync(legacyPath)) return result;
+
+  const legacyEnv = parseEnvFile(legacyPath);
+  const xdgEnv = parseEnvFile(xdgPath);
+  let migrated = migrateKeysFromLegacy({
+    legacyEnv,
+    xdgEnv,
+    keyFilter: (key) => MIGRATABLE_POINTER_KEYS.has(key) || CREDENTIAL_ENV_KEYS.has(key),
+  });
+  migrated = backfillFromOpEnvCatalog({ migrated, xdgEnv, homeDir });
+
+  if (Object.keys(migrated).length === 0) return result;
+
+  writeEnvValues(xdgPath, migrated);
+  result.performed = true;
+  result.migrated = migrated;
+  return result;
+}

package/lib/config/schema.mjs

@@ -7,7 +7,7 @@
  *
  * Schema v1 covers: alias, deployment, providers, sources, intakePolicy,
  * autoEmbed, ingest, telemetry.
- * Tier model selection lives in `specialists/registry.json` only — this config
+ * Tier model selection lives in `specialists/org` only — this config
  * file is intentionally not a second edit surface for model assignments.
  * Later phases (6, 7b) extend it with `resources` and `costs` blocks
  * without bumping the version — additive keys are allowed.
@@ -21,7 +21,7 @@ export const CONFIG_SCHEMA_VERSION = 1;
 
 export const DEPLOYMENT_MODES = ['solo', 'team', 'enterprise'];
 export const MCP_BROKER_VALUES = ['auto', 'on', 'off'];
-export const DEFAULT_PROFILE_ID = 'rnd';
+export const DEFAULT_SCOPE_ID = 'rnd';
 
 export const SURFACES = ['claude', 'opencode', 'codex', 'copilot', 'vscode', 'cursor'];
 
@@ -59,7 +59,7 @@ export const DEFAULT_PROJECT_CONFIG = Object.freeze({
     defaults: Object.freeze({}),
     types: Object.freeze({}),
   }),
-  profile: DEFAULT_PROFILE_ID,
+  scope: DEFAULT_SCOPE_ID,
   autoEmbed: false,
   ingest: Object.freeze({
     strategy: 'adapter',
@@ -79,7 +79,7 @@ export const DEFAULT_PROJECT_CONFIG = Object.freeze({
   }),
   models: Object.freeze({
     visibility: Object.freeze({
-      mode: 'all_configured',
+      mode: 'tier_defaults',
       include: [],
       exclude: [],
       providers: {},
@@ -156,7 +156,7 @@ export const FIELD_RULES = {
       types: { type: 'object', required: false },
     },
   },
-  profile: { type: 'string', required: false, maxLength: 40 },
+  scope: { type: 'string', required: false, maxLength: 40 },
   autoEmbed: { type: 'boolean', required: false },
   ingest: {
     type: 'object',

package/lib/config/source-targets.mjs

@@ -309,3 +309,83 @@ export function resolveKnownSourcesFromTargets(targets) {
 
   return sources;
 }
+
+// Team bindings take precedence over project config, which takes precedence over
+// legacy env. Resolution is by typed selector signature — no substring guessing —
+// so a team's effective sources are stable and conflict-free.
+
+export function resolveTeamSources(teamId, { registry, config, env = process.env } = {}) {
+  const team = registry?.teams?.[teamId];
+  const teamTargets = Array.isArray(team?.sources)
+    ? team.sources.map((s) => ({
+        ...normalizeConfigTarget(s),
+        provenance: `team:${teamId}`,
+        ...(s.filters && typeof s.filters === 'object' ? { filters: s.filters } : {}),
+      }))
+    : [];
+  const configTargets = (config?.sources?.targets ?? []).map(normalizeConfigTarget);
+  const envTargets = legacyEnvSourceTargets(env);
+  return mergeSourceTargets(teamTargets, mergeSourceTargets(configTargets, envTargets));
+}
+
+// Per-target embed records that honor each target's own filters (jira jql,
+// github refs/limit, slack oldest) and tag the record with the owning teamId and
+// targetId so observations stay retrievable by team scope rather than a global
+// pool. Falls back to the same defaults as targetsToEmbedSources when a target
+// declares no filters.
+
+export function targetsToEmbedSourcesWithFilters(targets, { teamId = null } = {}) {
+  const sources = [];
+  const tag = (rec, target) => ({
+    ...rec,
+    ...(teamId ? { teamId } : {}),
+    targetId: target.id,
+  });
+
+  for (const target of targets) {
+    const f = target.filters ?? {};
+    const sel = target.selector ?? {};
+    switch (target.provider) {
+      case 'github':
+        sources.push(tag({
+          provider: 'github',
+          repos: [sel.repo],
+          refs: Array.isArray(f.refs) ? f.refs : ['prs', 'issues', 'commits'],
+          limit: Number.isInteger(f.limit) ? f.limit : 25,
+        }, target));
+        break;
+      case 'jira':
+        sources.push(tag({
+          provider: 'jira',
+          project: sel.project,
+          refs: ['issues'],
+          ...(typeof f.jql === 'string' ? { jql: f.jql } : {}),
+          limit: Number.isInteger(f.limit) ? f.limit : 50,
+        }, target));
+        break;
+      case 'linear':
+        sources.push(tag({
+          provider: 'linear',
+          team: sel.team,
+          refs: ['issues'],
+          ...(Array.isArray(f.states) ? { states: f.states } : {}),
+          limit: Number.isInteger(f.limit) ? f.limit : 50,
+        }, target));
+        break;
+      case 'slack':
+        sources.push(tag({
+          provider: 'slack',
+          channels: [sel.channel],
+          intent: sel.intent ?? 'internal',
+          refs: ['messages'],
+          oldest: Number.isInteger(f.oldest) ? f.oldest : 86400,
+          limit: Number.isInteger(f.limit) ? f.limit : 50,
+        }, target));
+        break;
+      default:
+        break;
+    }
+  }
+
+  return sources;
+}

package/lib/contracts/validate.mjs

@@ -1,12 +1,11 @@
 /**
- * lib/contracts/validate.mjs — Validate specialists/contracts.json at sync time + at handoff.
+ * lib/contracts/validate.mjs — Validate specialists/org contracts at sync time + at handoff.
  *
  * Three validation tiers:
- *   1. Schema shape: contracts.json conforms to contracts.schema.json (minimal
- *      validator — top-level required fields, contract entry required fields).
+ *   1. Schema shape: unified registry conforms to unified-registry.schema.json.
  *   2. Cross-file refs: every output.schema points to a real file in lib/contract-schemas/,
- *      every producer/consumer name resolves to an agent or persona in
- *      specialists/registry.json, every well-known event/intake string is reachable.
+ *      every producer/consumer name resolves to a specialist in the unified registry,
+ *      every well-known event/intake string is reachable.
  *   3. Runtime handoff: a single artifact validated against the schema referenced
  *      by a producer→consumer contract, with mustContain post-conditions.
  *
@@ -25,13 +24,11 @@ import {
 import { inferArtifactTypeFromPath } from '../artifact-type-from-path.mjs';
 import { POSTCONDITIONS, validateBinaryPostconditions } from '../specialists/postconditions.mjs';
 import { logViolation } from './violation-log.mjs';
+import { loadRegistry } from '../registry/loader.mjs';
 
 const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
-const CONTRACTS_PATH = join(REPO_ROOT, 'specialists', 'contracts.json');
-const CONTRACTS_SCHEMA_PATH = join(REPO_ROOT, 'specialists', 'contracts.schema.json');
-const REGISTRY_PATH = join(REPO_ROOT, 'specialists', 'registry.json');
 
-const WELL_KNOWN_PRODUCERS = new Set(['user', 'oncall', 'incident-system', '*']);
+const WELL_KNOWN_PRODUCERS = new Set(['user', 'oncall', 'incident-system', 'construct', '*']);
 const WELL_KNOWN_CONSUMERS = new Set(['user', 'construct']);
 
 function readJson(path) {
@@ -39,40 +36,50 @@ function readJson(path) {
 }
 
 /**
- * Validate specialists/contracts.json shape and cross-file references.
- * Returns { ok, errors[] } — errors is empty on success.
+ * Validate the unified registry's contracts (shape + cross-file references).
+ * Reads registry.contracts via loadRegistry; an explicit contractsPath
+ * overrides for legacy/standalone files. Returns { ok, errors[] } — errors
+ * is empty on success.
  */
 export function validateContractsFile({ contractsPath, registryPath, repoRoot = REPO_ROOT } = {}) {
-  const errors = [];
-
-  // When repoRoot is supplied but explicit paths are not, derive both from it
-  // so test fixtures and the consistency watcher can validate slices in a
-  // tmpdir without pointing at the live repo.
-  const cPath = contractsPath || join(repoRoot, 'specialists', 'contracts.json');
-  const rPath = registryPath || join(repoRoot, 'specialists', 'registry.json');
-  const schemaPath = join(repoRoot, 'specialists', 'contracts.schema.json');
-
-  if (!existsSync(cPath)) {
-    return { ok: false, errors: [`contracts file not found: ${cPath}`] };
-  }
-  if (!existsSync(schemaPath)) {
-    errors.push(`contracts schema missing: ${schemaPath}`);
-  }
-
-  let contracts;
-  try { contracts = readJson(cPath); }
-  catch (err) { return { ok: false, errors: [`contracts.json parse error: ${err.message}`] }; }
-
-  for (const key of ['version', 'terminalStates', 'severities', 'contracts']) {
-    if (!(key in contracts)) errors.push(`contracts.json missing top-level field: ${key}`);
-  }
-
-  const knownNames = collectAgentNames(rPath);
-
-  if (Array.isArray(contracts.contracts)) {
-    const ids = new Set();
-    contracts.contracts.forEach((c, idx) => {
-      const where = `contracts[${idx}]${c.id ? ` (${c.id})` : ''}`;
+   const errors = [];
+ 
+   // Load contracts from unified registry or explicit path
+   const registry = loadRegistry();
+   const specialistIds = new Set(Object.keys(registry.specialists));
+
+   let contractsArray;
+   if (contractsPath) {
+     const cPath = contractsPath;
+     const schemaPath = join(repoRoot, 'specialists', 'contracts.schema.json');
+     if (!existsSync(cPath)) {
+       return { ok: false, errors: [`contracts file not found: ${cPath}`] };
+     }
+     if (!existsSync(schemaPath)) {
+       errors.push(`contracts schema missing: ${schemaPath}`);
+     }
+     const raw = readJson(cPath);
+     for (const key of ['version', 'terminalStates', 'severities', 'contracts']) {
+       if (!(key in raw)) errors.push(`contracts file missing top-level field: ${key}`);
+     }
+     contractsArray = raw.contracts || [];
+   } else {
+     // From unified registry - normalize contracts to array format
+     contractsArray = Object.values(registry.contracts || {});
+     // Support old-format contracts object with .contracts array
+     if (Array.isArray(contractsArray) && contractsArray.length === 0 && registry.contracts?.contracts) {
+       contractsArray = registry.contracts.contracts;
+     }
+   }
+
+   const knownNames = registryPath
+     ? collectAgentNames(registryPath)
+     : new Set(Object.keys(registry.specialists).concat(Object.values(registry.specialists).map(s => s.name)));
+
+   if (Array.isArray(contractsArray)) {
+     const ids = new Set();
+     contractsArray.forEach((c, idx) => {
+       const where = `contracts[${idx}]${c.id ? ` (${c.id})` : ''}`;
       if (!c.id) errors.push(`${where}: missing id`);
       else if (!/^[a-z0-9][a-z0-9-]*$/.test(c.id)) errors.push(`${where}: id must be kebab-case`);
       else if (ids.has(c.id)) errors.push(`${where}: duplicate id`);
@@ -124,7 +131,7 @@ function collectAgentNames(registryPath) {
     const registry = readJson(registryPath);
     if (registry.orchestrator?.name) names.add(registry.orchestrator.name);
     if (registry.orchestrator?.displayName) names.add(registry.orchestrator.displayName);
-    for (const s of registry.specialists || []) {
+    for (const s of Object.values(registry.specialists || {})) {
       if (s?.name) names.add(s.name);
       if (s?.displayName) names.add(s.displayName);
     }
@@ -135,14 +142,21 @@ function collectAgentNames(registryPath) {
 /**
  * Look up a contract by producer/consumer pair (and optional id).
  */
-export function findContract({ producer, consumer, id, contractsPath = CONTRACTS_PATH }) {
-  if (!existsSync(contractsPath)) return null;
-  let contracts;
-  try { contracts = readJson(contractsPath); } catch { return null; }
-  const list = contracts.contracts || [];
-  if (id) return list.find((c) => c.id === id) || null;
-  return list.find((c) => c.producer === producer && c.consumer === consumer) || null;
-}
+export function findContract({ producer, consumer, id, contractsPath }) {
+   if (contractsPath) {
+     if (!existsSync(contractsPath)) return null;
+     try {
+       const contracts = readJson(contractsPath);
+       const list = contracts.contracts || [];
+       if (id) return list.find((c) => c.id === id) || null;
+       return list.find((c) => c.producer === producer && c.consumer === consumer) || null;
+     } catch { return null; }
+   }
+   // Default: use unified registry
+   const registry = loadRegistry();
+   if (id) return registry.contracts[id] || null;
+   return Object.values(registry.contracts).find((c) => c.producer === producer && c.consumer === consumer) || null;
+ }
 
 /**
  * Validate a single artifact against its contract at handoff time.
@@ -168,7 +182,7 @@ export function validateHandoff(opts = {}) {
     id,
     artifact,
     packet,
-    contractsPath = CONTRACTS_PATH,
+    contractsPath,
     repoRoot = REPO_ROOT,
     enforcement = 'block',
   } = opts;
@@ -216,6 +230,14 @@ export function validateHandoff(opts = {}) {
       : { ok: true, warnings: [`no contract found for ${producer}→${consumer}`], contract: null };
   }
 
+  // Team boundary validation: check if cross-team handoff requires approvals.
+  if (contract.teamBoundary?.crosses && Array.isArray(contract.teamBoundary.requiresApprovalFrom)) {
+    const teamBoundaryErrors = validateTeamBoundary(contract);
+    for (const err of teamBoundaryErrors) {
+      errors.push(err);
+    }
+  }
+
   // A handoff carries a producer's output, which is the consumer's input. The
   // input contract is what the consumer expects to receive; check mustContain
   // against that first. Output.schema validation only applies when the artifact
@@ -282,6 +304,52 @@ function hasField(obj, field) {
   return Object.prototype.hasOwnProperty.call(obj, field) && obj[field] != null && obj[field] !== '';
 }
 
+/**
+ * Validate team boundary enforcement on a contract.
+ * Returns array of error strings (empty if validation passes).
+ *
+ * Team boundaries are declarative metadata that enforce organizational
+ * separation of concerns. A contract.teamBoundary.requiresApprovalFrom
+ * lists teams that must explicitly approve before the handoff can complete.
+ */
+function validateTeamBoundary(contract = {}) {
+  const errors = [];
+  const boundary = contract.teamBoundary || {};
+
+  if (!boundary.crosses) return errors;
+  if (!Array.isArray(boundary.requiresApprovalFrom) || boundary.requiresApprovalFrom.length === 0) {
+    return errors;
+  }
+
+  // Check that producer and consumer teams are declared.
+  if (!boundary.producerTeam) {
+    errors.push(`team boundary marked as crossing but producerTeam is missing in contract ${contract.id}`);
+  }
+  if (!boundary.consumerTeam) {
+    errors.push(`team boundary marked as crossing but consumerTeam is missing in contract ${contract.id}`);
+  }
+
+  // Load registry to verify team ids exist.
+  try {
+    const registry = loadRegistry();
+    for (const teamId of boundary.requiresApprovalFrom) {
+      if (!registry.teams?.[teamId]) {
+        errors.push(`team boundary references unknown team: ${teamId} (in contract ${contract.id})`);
+      }
+    }
+    if (boundary.producerTeam && !registry.teams?.[boundary.producerTeam]) {
+      errors.push(`contract ${contract.id}: producerTeam '${boundary.producerTeam}' not found in registry`);
+    }
+    if (boundary.consumerTeam && !registry.teams?.[boundary.consumerTeam]) {
+      errors.push(`contract ${contract.id}: consumerTeam '${boundary.consumerTeam}' not found in registry`);
+    }
+  } catch (err) {
+    errors.push(`failed to validate team boundary for contract ${contract.id}: ${err.message}`);
+  }
+
+  return errors;
+}
+
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
 
 function parseArtifactFrontmatter(text) {

package/lib/decisions/golden.mjs

@@ -1,3 +1,4 @@
+import { loadRegistry } from '../registry/loader.mjs';
 /**
  * lib/decisions/golden.mjs — behavioral golden snapshot of core surfaces.
  *
@@ -38,8 +39,8 @@ export function buildSurfaceSnapshot({ repoRoot = REPO_ROOT } = {}) {
   }
   snapshot.commands.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 
-  const registry = JSON.parse(readFileSync(join(repoRoot, 'specialists', 'registry.json'), 'utf8'));
-  snapshot.agents = (registry.specialists || []).map((s) => s.name).sort();
+  const registry = loadRegistry({ rootDir: repoRoot });
+  snapshot.agents = Object.values(registry.specialists || {}).map((s) => s.name).sort();
 
   const settings = JSON.parse(readFileSync(join(repoRoot, 'platforms', 'claude', 'settings.template.json'), 'utf8'));
   for (const event of HOOK_EVENTS) {

package/lib/decisions/registry.mjs

@@ -8,7 +8,7 @@
  *
  * Three decision sources are indexed:
  *   - ADRs           docs/decisions/adr/*.md            (status + supersedes parsed from body)
- *   - Contracts      specialists/contracts.json (executable postconditions = enforcement)
+ *   - Contracts      specialists/org (executable postconditions = enforcement)
  *   - Rules          rules/**\/*.md            (enforcement link via frontmatter; bead wvbf.4)
  *
  * Enforcement bindings are discovered by scanning tests/ and lib/hooks/ for an
@@ -24,6 +24,7 @@ import { join, dirname, resolve, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { readRuleFile } from '../rules-read.mjs';
+import { loadRegistry } from '../registry/loader.mjs';
 
 export const DECISION_STATUSES = ['proposed', 'accepted', 'superseded', 'deprecated'];
 
@@ -152,11 +153,15 @@ function adrDecisions({ repoRoot, bindings }) {
 }
 
 function contractDecisions({ repoRoot, bindings }) {
-  const file = join(repoRoot, 'specialists', 'contracts.json');
-  if (!existsSync(file)) return [];
-  const parsed = JSON.parse(readFileSync(file, 'utf8'));
+  const registryFile = join('specialists', 'org');
+  let contractsArray;
+  try {
+    contractsArray = Object.values(loadRegistry({ rootDir: repoRoot, skipValidation: true }).contracts || {});
+  } catch {
+    return [];
+  }
   const out = [];
-  for (const c of parsed.contracts || []) {
+  for (const c of contractsArray) {
     const checks = [];
     let advisoryPostconditions = 0;
     for (const pc of c.postconditions || []) {
@@ -171,7 +176,7 @@ function contractDecisions({ repoRoot, bindings }) {
       status: 'accepted',
       supersedes: null,
       supersededBy: null,
-      file: relative(repoRoot, file),
+      file: registryFile,
       lastVerifiedAt: null,
       enforcingTests,
       enforcingChecks: checks,