@geraldmaron/construct 1.2.2 → 1.3.0

package/lib/embed/demand-fetch.mjs

@@ -149,11 +149,36 @@ export function matchSourceFromQuery(query, env = process.env, cwd = process.cwd
  * @param {object} [opts.env]        - Env override
  * @returns {Promise<DemandFetchResult>}
  */
-export async function demandFetch({ query, rootDir, env, cwd } = {}) {
+export async function demandFetch({ query, rootDir, env, cwd, teamId = null, targetIds = null, registry: injectedRegistry = null, providerRegistry = null } = {}) {
   const resolvedEnv = env ?? loadConstructEnv();
   const root = rootDir ?? (resolvedEnv.CX_DATA_DIR?.trim() || homedir());
   const projectRoot = cwd ?? root;
 
+  // Team-scoped fetch: resolve the team's declared sources and drive the fetch
+  // from them. A requested target outside the team is a typed OUT_OF_SCOPE error
+  // — never a silent wrong-source fetch. Resolution is by typed selector, so the
+  // team's effective sources are stable rather than substring-matched.
+  if (teamId) {
+    const { resolveTeamSources } = await import('../config/source-targets.mjs');
+    let registry = injectedRegistry;
+    if (!registry) {
+      const { loadRegistry } = await import('../registry/loader.mjs');
+      try { registry = loadRegistry({ rootDir: projectRoot, skipValidation: true }); } catch { registry = null; }
+    }
+    let targets = resolveTeamSources(teamId, { registry, config: {}, env: resolvedEnv });
+    if (Array.isArray(targetIds) && targetIds.length) {
+      const known = new Set(targets.map((t) => t.id));
+      const unknown = targetIds.filter((id) => !known.has(id));
+      if (unknown.length) {
+        return { ok: false, reason: 'OUT_OF_SCOPE', message: `target_ids not in team ${teamId}: ${unknown.join(', ')}`, items: [], teamId, targetIds };
+      }
+      targets = targets.filter((t) => targetIds.includes(t.id));
+    }
+    if (targets.length) {
+      return demandFetchTeam({ teamId, targets, rootDir: root, env: resolvedEnv, providerRegistry });
+    }
+  }
+
   const match = matchSourceFromQuery(query, resolvedEnv, projectRoot);
 
   // Self-referential queries about Construct itself → route to knowledge_search,
@@ -259,7 +284,7 @@ export async function demandFetch({ query, rootDir, env, cwd } = {}) {
         category: 'insight',
         summary: item.title ?? item.summary ?? item.id,
         content: buildObservationContent(item, match),
-        tags: ['demand-fetch', match.provider, match.ref ?? match.provider],
+        tags: ['demand-fetch', match.provider, match.ref ?? match.provider, ...(teamId ? [`team:${teamId}`] : [])],
         confidence: 0.9,
         source: `demand-fetch:${match.provider}`,
       });
@@ -275,6 +300,7 @@ export async function demandFetch({ query, rootDir, env, cwd } = {}) {
     match,
     written,
     errors: errorItems.length ? errorItems : undefined,
+    ...(teamId ? { teamId } : {}),
   };
 }
 
@@ -451,6 +477,92 @@ function buildReadCalls(match, env, cwd = process.cwd()) {
   return [];
 }
 
+// Read calls for one resolved team source, honoring the target's own filters
+// (jira jql, github refs/limit, slack oldest) rather than the generic defaults.
+
+function buildReadCallsForTarget(target) {
+  const sel = target.selector ?? {};
+  const f = target.filters ?? {};
+  const display = `${target.provider}/${sel.repo ?? sel.project ?? sel.team ?? sel.channel ?? target.id}`;
+  switch (target.provider) {
+    case 'github': {
+      const opts = { repos: [sel.repo], limit: Number.isInteger(f.limit) ? f.limit : 25 };
+      const refs = Array.isArray(f.refs) ? f.refs : ['meta', 'readme', 'docs', 'prs', 'issues', 'commits'];
+      return refs.map((ref) => ({ ref, opts, display }));
+    }
+    case 'jira': {
+      const jql = typeof f.jql === 'string'
+        ? f.jql
+        : `project = "${sel.project}" AND statusCategory != Done ORDER BY updated DESC`;
+      return [{ ref: 'issues', opts: { jql, limit: Number.isInteger(f.limit) ? f.limit : 50 }, display }];
+    }
+    case 'linear':
+      return [{ ref: 'issues', opts: { team: sel.team, limit: Number.isInteger(f.limit) ? f.limit : 50 }, display }];
+    case 'slack':
+      return [{ ref: 'messages', opts: { channels: [sel.channel], oldest: Number.isInteger(f.oldest) ? f.oldest : 86400, limit: Number.isInteger(f.limit) ? f.limit : 50 }, display }];
+    default:
+      return [];
+  }
+}
+
+// Drive the fetch from a team's resolved sources: one provider read per target,
+// every observation tagged team:<id> + target:<id> so results stay retrievable by
+// team scope. providerRegistry is injectable for hermetic tests.
+
+async function demandFetchTeam({ teamId, targets, rootDir, env, providerRegistry = null }) {
+  let registry = providerRegistry;
+  if (!registry) {
+    const { ProviderRegistry } = await import('./providers/registry.mjs');
+    registry = await ProviderRegistry.fromEnv(env);
+  }
+
+  const allItems = [];
+  const errors = [];
+  let written = 0;
+
+  for (const target of targets) {
+    const provider = registry.get(target.provider);
+    if (!provider) {
+      errors.push({ provider: target.provider, targetId: target.id, message: `provider "${target.provider}" not registered` });
+      continue;
+    }
+    for (const { ref, opts, display } of buildReadCallsForTarget(target)) {
+      try {
+        const items = await provider.read(ref, opts);
+        for (const item of items ?? []) {
+          if (item.type === 'error') { errors.push(item); continue; }
+          allItems.push(item);
+          try {
+            addObservation(rootDir, {
+              role: 'construct',
+              category: 'insight',
+              summary: item.title ?? item.summary ?? item.id,
+              content: buildObservationContent(item, { provider: target.provider, ref: target.id, display }),
+              tags: ['demand-fetch', 'team', target.provider, `team:${teamId}`, `target:${target.id}`],
+              confidence: 0.88,
+              source: `demand-fetch:team:${teamId}:${target.id}`,
+            });
+            written++;
+          } catch (err) { process.stderr.write('[demand-fetch.mjs] team-store-obs: ' + (err?.message ?? String(err)) + '\n'); }
+        }
+      } catch (err) {
+        errors.push({ provider: target.provider, targetId: target.id, message: err.message });
+      }
+    }
+  }
+
+  return {
+    ok: errors.length === 0 || allItems.length > 0,
+    reason: allItems.length ? 'team_fetched' : 'team_empty',
+    message: `Fetched ${allItems.length} item(s) from team ${teamId} (${targets.length} source(s)), stored ${written} observation(s)`,
+    items: allItems,
+    teamId,
+    targetIds: targets.map((t) => t.id),
+    written,
+    errors: errors.length ? errors : undefined,
+  };
+}
+
 function buildObservationContent(item, match) {
   const lines = [`Source: ${match.display}`, `Provider: ${match.provider}`];
   if (item.url) lines.push(`URL: ${item.url}`);

package/lib/embed/docs-lifecycle.mjs

@@ -227,9 +227,11 @@ export async function runDocsLifecycle(opts) {
   const actions = [];
   const recommendations = [];
   const conflicts = [];
-
-  // Auto-suppress stale recommendations before generating new ones
-  const suppressed = autoSuppressStale();
+  const localTargets = targets.filter((target) => target.access !== 'remote' && target.path);
+  let suppressed = 0;
+  for (const target of localTargets) {
+    suppressed += autoSuppressStale({ project: target.path });
+  }
 
   for (const target of targets) {
     const gaps = detectDocGaps(target, { snapshot, roleLens });
@@ -266,6 +268,7 @@ export async function runDocsLifecycle(opts) {
         recencyBonus: 2,
         sourceSignalIds: payload.intakeIds || [],
         lane: gap.lane,
+        project: target.path,
       });
       recommendations.push(recResult);
       allGaps.push({ ...gap, target: targetLabel(target), recommendation: recResult });
@@ -276,13 +279,14 @@ export async function runDocsLifecycle(opts) {
       const artifactRecs = recommendArtifacts(snapshot, { rootDir: target.path });
       for (const rec of artifactRecs) {
         // Use recommendation store for dedup
-        const { active, existing } = isRecommendationActive(rec.type, rec.title);
+        const { active, existing } = isRecommendationActive(rec.type, rec.title, { project: target.path });
         if (!active) {
           const recResult = createRecommendation({
             type: rec.type,
             title: rec.title,
             reason: rec.reason,
             signalCount: 1,
+            project: target.path,
           });
           recommendations.push(recResult);
           allGaps.push({
@@ -340,7 +344,7 @@ export async function runDocsLifecycle(opts) {
     }
   }
 
-  const stats = recommendationStats();
+  const stats = recommendationStats({ project: localTargets[0]?.path });
 
   return {
     gaps: allGaps,

package/lib/embed/intake-metrics.mjs

@@ -2,8 +2,8 @@
  * lib/embed/intake-metrics.mjs — Intake pipeline observability.
  *
  * Aggregates volume, velocity, processing time, and acceptance rate from
- * the filesystem intake queue. Designed for the dashboard /api/insights
- * endpoint and the `construct intake metrics` CLI.
+ * the filesystem intake queue. Consumed by `construct intake metrics` and
+ * MCP insight tools.
  *
  * Data sources:
  *   .cx/intake/pending/   — JSON files waiting for triage

package/lib/embed/notifications.mjs

@@ -1,9 +1,8 @@
 /**
  * lib/embed/notifications.mjs — embed action notification bus.
  *
- * Decoupled event emitter for embed daemon → dashboard SSE.
- * The dashboard server subscribes to this bus; the daemon emits events.
- * Slack stub is wired but no-ops without config.
+ * In-process event emitter for embed daemon lifecycle and operator toasts.
+ * Slack webhook delivery is optional via notifySlack.
  */
 
 import { EventEmitter } from 'node:events';

package/lib/embed/recommendation-store.mjs

@@ -24,8 +24,9 @@ import { cxDir } from '../paths.mjs';
 const DEFAULT_SUPPRESS_DAYS = 7;
 const SUPERSEDE_WITHIN_HOURS = 72;
 
-function recommendationPaths() {
-  const storeDir = join(cxDir(), 'intake');
+function recommendationPaths({ rootDir, project } = {}) {
+  const baseDir = rootDir || project;
+  const storeDir = baseDir ? join(baseDir, '.cx', 'intake') : join(cxDir(), 'intake');
   return {
     storeDir,
     logFile: join(storeDir, 'recommendations.jsonl'),
@@ -36,16 +37,16 @@ function recommendationPaths() {
 /**
  * Ensure store directory exists.
  */
-function ensureDir() {
-  const { storeDir } = recommendationPaths();
+function ensureDir(opts = {}) {
+  const { storeDir } = recommendationPaths(opts);
   if (!existsSync(storeDir)) mkdirSync(storeDir, { recursive: true });
 }
 
 /**
  * Read the index (fast lookup).
  */
-function readIndex() {
-  const { indexFile } = recommendationPaths();
+function readIndex(opts = {}) {
+  const { indexFile } = recommendationPaths(opts);
   if (!existsSync(indexFile)) return {};
   try {
     return JSON.parse(readFileSync(indexFile, 'utf8'));
@@ -57,9 +58,9 @@ function readIndex() {
 /**
  * Write the index.
  */
-function writeIndex(index) {
-  const { indexFile } = recommendationPaths();
-  ensureDir();
+function writeIndex(index, opts = {}) {
+  const { indexFile } = recommendationPaths(opts);
+  ensureDir(opts);
   writeFileSync(indexFile, JSON.stringify(index, null, 2) + '\n');
 }
 
@@ -86,9 +87,10 @@ function dedupKey(type, title) {
 export function createRecommendation({ type, title, reason, signalCount = 1, customerImpact = 0, recencyBonus = 0, strategicBonus = 0, sourceSignalIds = [], lane, project, env }) {
   if (!type || !title) throw new Error('type and title are required');
 
-  ensureDir();
+  const pathOpts = { rootDir: project };
+  ensureDir(pathOpts);
   const key = dedupKey(type, title);
-  const index = readIndex();
+  const index = readIndex(pathOpts);
 
   if (index[key]) {
     const existing = index[key];
@@ -106,7 +108,7 @@ export function createRecommendation({ type, title, reason, signalCount = 1, cus
       updated.score = score;
       updated.priority = priorityTier(score);
       index[key] = updated;
-      writeIndex(index);
+      writeIndex(index, pathOpts);
 
       return { id: existing.id, dedupKey: key, priority: updated.priority, score, existing: true, updatedAt: updated.lastSeen };
     }
@@ -139,10 +141,10 @@ export function createRecommendation({ type, title, reason, signalCount = 1, cus
     enrichedBy: null,
   };
 
-  appendFileSync(recommendationPaths().logFile, JSON.stringify(rec) + '\n', 'utf8');
+  appendFileSync(recommendationPaths(pathOpts).logFile, JSON.stringify(rec) + '\n', 'utf8');
 
   index[key] = rec;
-  writeIndex(index);
+  writeIndex(index, pathOpts);
 
   emitBestEffort('recommendation.generated', {
     project: project || '',
@@ -202,7 +204,7 @@ export function supersedeRecommendation(dedupKey, supersedingId) {
  * List active recommendations (filesystem-only).
  */
 export function listActiveRecommendations({ type, priority, limit = 20, project, env } = {}) {
-  const index = readIndex();
+  const index = readIndex({ rootDir: project });
   const now = new Date();
   let results = Object.values(index).filter(rec => {
     if (rec.dismissedAt) {
@@ -222,8 +224,9 @@ export function listActiveRecommendations({ type, priority, limit = 20, project,
     .slice(0, limit);
 }
 
-export function autoSuppressStale() {
-  const index = readIndex();
+export function autoSuppressStale({ project } = {}) {
+  const pathOpts = { rootDir: project };
+  const index = readIndex(pathOpts);
   const now = Date.now();
   let suppressed = 0;
 
@@ -255,7 +258,7 @@ export function autoSuppressStale() {
     }
   }
 
-  if (suppressed) writeIndex(index);
+  if (suppressed) writeIndex(index, pathOpts);
   return suppressed;
 }
 
@@ -291,8 +294,8 @@ export function reviveRecommendation(dedupKey, { signalCount = 1, sourceSignalId
   return { success: true };
 }
 
-export function recommendationStats() {
-  const index = readIndex();
+export function recommendationStats({ project } = {}) {
+  const index = readIndex({ rootDir: project });
   const entries = Object.values(index);
   const byPriority = {};
   let active = 0, dismissed = 0, superseded = 0;
@@ -314,9 +317,9 @@ export function recommendationStats() {
   };
 }
 
-export function isRecommendationActive(type, title) {
+export function isRecommendationActive(type, title, { project } = {}) {
   const key = dedupKey(type, title);
-  const index = readIndex();
+  const index = readIndex({ rootDir: project });
   const rec = index[key];
   if (!rec) return { active: false, existing: null };
   if (rec.dismissedAt || rec.supersededAt) return { active: false, existing: rec };

package/lib/embed/role-framing.mjs

@@ -7,22 +7,17 @@
  *   3. Renders a "Role Lens" section for inclusion in snapshots/roadmaps
  */
 
-import { readFileSync } from 'node:fs';
-import { join, dirname } 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 _registryCache = null;
 
 function loadRegistry() {
   if (_registryCache) return _registryCache;
   try {
-    _registryCache = JSON.parse(readFileSync(REGISTRY_PATH, 'utf8'));
+    _registryCache = loadAssembledRegistry();
   } catch (err) {
     process.stderr.write('[role-framing.mjs] loadRegistry: ' + (err?.message ?? String(err)) + '\n');
-    _registryCache = { specialists: [] };
+    _registryCache = { specialists: {} };
   }
   return _registryCache;
 }
@@ -35,7 +30,7 @@ function loadRegistry() {
 export function getOrientation(roleName) {
   if (!roleName) return null;
   const registry = loadRegistry();
-  const agent = (registry.specialists ?? []).find((a) => a.name === roleName);
+  const agent = Object.values(registry.specialists ?? {}).find((a) => a.name === roleName);
   return agent?.embedOrientation ?? null;
 }
 

package/lib/embedded-contract/capability.mjs

@@ -23,6 +23,7 @@ import { resolveModelTiers } from '../model-registry.mjs';
 import { readSkillFrontmatter } from '../sync/skill-frontmatter.mjs';
 import { loadPluginRegistry } from '../plugin-registry.mjs';
 import { listWorkflowDefs } from './workflow-defs.mjs';
+import { loadRegistry } from '../registry/loader.mjs';
 import { APPROVAL_MODES } from './audit.mjs';
 
 const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
@@ -111,8 +112,9 @@ function buildModels(env) {
 
 function buildPolicies(rootDir, warnings) {
   try {
-    const raw = JSON.parse(readFileSync(join(rootDir, 'specialists', 'policy-inventory.json'), 'utf8'));
-    const arr = Array.isArray(raw) ? raw : (raw.policies || Object.values(raw));
+    const registry = loadRegistry({ rootDir, skipValidation: true });
+    const policies = registry.policies || {};
+    const arr = Array.isArray(policies) ? policies : Object.values(policies);
     return arr.map((p) => ({ id: p.id, enforcement: p.enforcement, mode: p.mode, description: p.description }));
   } catch (err) {
     warnings.push(`Policy inventory unavailable: ${err.message}`);

package/lib/embedded-contract/contract-version.mjs

@@ -8,7 +8,7 @@
  * CONTRACT_VERSION so an embedding application can negotiate compatibility
  * without reading internal registries.
  *
- * Distinct from specialists/contracts.json `version` (handoff contracts) and
+ * Distinct from specialists/org `version` (handoff contracts) and
  * lib/plugin-registry.mjs `MANIFEST_VERSION` (plugin manifests); those version
  * unrelated internal surfaces.
  */

package/lib/env-config.mjs

@@ -88,7 +88,7 @@ const ENV_SHADOW_IGNORE = new Set([
  */
 const ENV_SHADOW_WARN = new Set([
   'OPENROUTER_API_KEY', 'ANTHROPIC_API_KEY', 'OPENAI_API_KEY',
-  'DASHBOARD_PORT', 'MEMORY_PORT', 'BRIDGE_PORT',
+  'MEMORY_PORT', 'BRIDGE_PORT',
   'CONSTRUCT_INSTANCE_ID',
   'CONSTRUCT_DEPLOYMENT_MODE',
 ]);
@@ -155,7 +155,7 @@ export function loadConstructEnv({ rootDir, homeDir = os.homedir(), env = proces
   }
 
   // process.env is the base; .env-file values override shell values so that
-  // credentials set in the dashboard always win over stale shell exports.
+  // credentials set in config.env always win over stale shell exports.
   // Materialized credentials from `op run` (or an explicit export) win over stored
   // op:// references so one 1Password auth per invocation is enough.
   const merged = { ...env, ...fileEnv };

package/lib/flavors/loader.mjs

@@ -2,12 +2,12 @@
  * lib/flavors/loader.mjs — Role flavor overlay loader and validator.
  *
  * Reads frontmatter from skills/roles/<role>.<flavor>.md files, exposes:
- *   - listFlavors(role?, profile?) — overlays that apply to role and profile
+ *   - listFlavors(role?, scope?) — overlays that apply to role and scope
  *   - validateFlavor(path) — frontmatter conformance check against the schema
- *   - perRoleFlavorCount(profile) — flavor counts per role for cap enforcement
+ *   - perRoleFlavorCount(scope) — flavor counts per role for cap enforcement
  *
- * The cap is enforced at sync time and in lint-profiles.
- * Six flavors per role per profile is the current ceiling; bumping requires
+ * The cap is enforced at sync time and in lint-scopes.
+ * Six flavors per role per scope is the current ceiling; bumping requires
  * an ADR. Existing roles like qa already have 6, so the cap is set tight.
  */
 import fs from 'node:fs';
@@ -18,7 +18,8 @@ const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(MODULE_DIR, '..', '..');
 const FLAVORS_DIR = path.join(REPO_ROOT, 'skills', 'roles');
 
-export const FLAVOR_CAP_PER_ROLE_PER_PROFILE = 6;
+export const FLAVOR_CAP_PER_ROLE_PER_SCOPE = 6;
+export const FLAVOR_CAP_PER_ROLE_PER_PROFILE = FLAVOR_CAP_PER_ROLE_PER_SCOPE;
 
 // Files may start with an HTML comment block before the YAML frontmatter.
 // The /m flag lets ^ match line-start so we find the YAML wherever it sits.
@@ -79,30 +80,26 @@ export function listAllFlavors() {
  * Return overlays that match the given role (any-flavor for that role) and
  * apply to the given profile. Pass undefined for either to skip that filter.
  */
-export function listFlavors({ role, profile } = {}) {
+export function listFlavors({ role, scope, profile } = {}) {
+  const scopeId = scope ?? profile;
   return listAllFlavors().filter(({ frontmatter }) => {
     if (role) {
       const roleId = frontmatter.role || '';
       const baseRole = roleId.split('.')[0];
       if (baseRole !== role && roleId !== role) return false;
     }
-    if (profile) {
-      const profiles = frontmatter.profiles;
-      if (!Array.isArray(profiles) || profiles.length === 0) return true;
-      if (!profiles.includes(profile)) return false;
+    if (scopeId) {
+      const scopes = frontmatter.scopes ?? frontmatter.profiles;
+      if (!Array.isArray(scopes) || scopes.length === 0) return true;
+      if (!scopes.includes(scopeId)) return false;
     }
     return true;
   });
 }
 
-/**
- * Count flavor overlays per base role for a given profile.
- * Returns { [baseRole]: count }. Excludes the canonical base file (e.g.
- * architect.md) so only true flavors count toward the cap.
- */
-export function perRoleFlavorCount(profile = 'rnd') {
+export function perRoleFlavorCount(scope = 'rnd') {
   const counts = {};
-  for (const entry of listFlavors({ profile })) {
+  for (const entry of listFlavors({ scope })) {
     const roleId = entry.frontmatter.role || '';
     const isFlavor = roleId.includes('.');
     if (!isFlavor) continue;
@@ -129,8 +126,13 @@ export function validateFlavor(filePath) {
   if (!Array.isArray(fm.applies_to) || fm.applies_to.length === 0) {
     errors.push(`${filePath}: applies_to must be a non-empty array`);
   }
-  if (!Array.isArray(fm.profiles) || fm.profiles.length === 0) {
-    errors.push(`${filePath}: profiles must be a non-empty array; add a frontmatter line like \`profiles: [rnd]\``);
+  if (!Array.isArray(fm.scopes) && !Array.isArray(fm.profiles)) {
+    errors.push(`${filePath}: scopes must be a non-empty array; add \`scopes: [rnd]\``);
+  } else {
+    const scopes = fm.scopes ?? fm.profiles;
+    if (!Array.isArray(scopes) || scopes.length === 0) {
+      errors.push(`${filePath}: scopes must be a non-empty array; add \`scopes: [rnd]\``);
+    }
   }
   return errors;
 }

package/lib/graph/build-from-registry.mjs

@@ -3,7 +3,7 @@
  * authoritative declarative catalogs.
  *
  * Ingests registry/capabilities.json, lib/embedded-contract/workflow-defs.mjs,
- * and specialists/contracts.json into typed nodes and directed edges:
+ * and specialists/org into typed nodes and directed edges:
  *   capability --embeds-->     workflow      (embeddedWorkflow)
  *   test       --validates-->  capability    (verification.functional / hostEmulation / per-surface test)
  *   capability --uses-->       skill | rule  (skill + dependencies.skills/.rules)
@@ -16,6 +16,7 @@
  */
 
 import { existsSync, readFileSync, statSync } from 'node:fs';
+import { loadRegistry } from '../registry/loader.mjs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 
@@ -31,6 +32,23 @@ function existsRel(rootDir, rel) {
   return !!rel && existsSync(path.join(rootDir, rel));
 }
 
+function declarationImplFiles(cap, rootDir) {
+  const files = [];
+  if (cap.kind === 'workflow') {
+    files.push('lib/embedded-contract/workflow-invoke.mjs', 'lib/embedded-contract/workflow-defs.mjs');
+  }
+  if (cap.kind === 'document-type') {
+    files.push('lib/artifact-release-gate.mjs', 'lib/artifact-manifest.mjs');
+  }
+  if (cap.id === 'ingest.docling') {
+    files.push('lib/document-extract/docling-client.mjs', 'lib/ingest/docling-remote.mjs');
+  }
+  if (cap.id === 'mcp.tool-budget.trim') {
+    files.push('lib/mcp/tool-budget.mjs');
+  }
+  return [...new Set(files.filter((rel) => existsRel(rootDir, rel)))];
+}
+
 function hashFiles(rootDir, rels) {
   const h = createHash('sha256');
   for (const rel of rels) {
@@ -66,11 +84,11 @@ export function buildFromRegistry({ rootDir }) {
     });
   }
 
-  const contractsDoc = readJsonSafe(path.join(rootDir, 'specialists', 'contracts.json'));
-  for (const c of contractsDoc?.contracts ?? []) {
-    if (!c?.id) continue;
-    node('contract', c.id, c.id, { producer: c.producer ?? null, consumer: c.consumer ?? null });
-  }
+  const contractsDoc = loadRegistry({ rootDir });
+   for (const { id, producer, consumer } of Object.values(contractsDoc?.contracts ?? {})) {
+     if (!id) continue;
+     node('contract', id, id, { producer: producer ?? null, consumer: consumer ?? null });
+   }
 
   const registry = loadCapabilityRegistry({ rootDir });
   for (const cap of registry.capabilities ?? []) {
@@ -122,11 +140,17 @@ export function buildFromRegistry({ rootDir }) {
       node('contract', cid, cid, {});
       edge(capNode, 'governed_by', nodeId('contract', cid));
     }
+
+    for (const implRel of declarationImplFiles(cap, rootDir)) {
+      const fileNode = nodeId('file', implRel);
+      node('file', implRel, implRel, { path: implRel, exists: true, source: 'declaration' });
+      edge(fileNode, 'realizes', capNode);
+    }
   }
 
   const sourceHash = hashFiles(rootDir, [
     'registry/capabilities.json',
-    'specialists/contracts.json',
+    'specialists/org',
     'lib/embedded-contract/workflow-defs.mjs',
   ]);
 

package/lib/graph/staleness.mjs

@@ -11,7 +11,7 @@ import { loadGraph } from './store.mjs';
 
 export const GRAPH_SEED_FILES = [
   'registry/capabilities.json',
-  'specialists/contracts.json',
+  'specialists/org',
   'lib/embedded-contract/workflow-defs.mjs',
 ];