@kal-elsam/kairo-runtime 0.4.3 → 0.5.0

package/src/global/component-integration-cli.js

@@ -0,0 +1,302 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveHomeDir, harnessHomePaths } from "./paths.js";
+import { readGlobalState, writeGlobalState } from "./state.js";
+import { detectInstalledAdapters } from "./registry.js";
+import { resolveComponent } from "./component-registry.js";
+import { printJson } from "./json-output.js";
+import { formatCliCommand } from "./brand/cli.js";
+import { requireIntegrationProvider } from "./integrations/provider-registry.js";
+import { ensureIntegrationProvidersRegistered } from "./integrations/index.js";
+import { ENGRAM_INTEGRATION_STATUS } from "./integrations/engram-evidence.js";
+import { SDD_HEALTH } from "./integrations/sdd-evidence.js";
+import {
+  hasSuccessfulSddRollbackMutations, recordSddMaterialization, reconcileSddStateAfterRollback
+} from "./integrations/sdd-state.js";
+import { loadSddReceipt } from "./integrations/sdd-receipts.js";
+
+const DEFAULT_PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+
+const COMPONENT_PROVIDERS = Object.freeze({
+  "engram-memory": "engram",
+  "sdd-core": "sdd-core"
+});
+
+export async function assertComponentInstalled(componentId, { homeDir = resolveHomeDir() } = {}) {
+  const state = await readGlobalState(harnessHomePaths(homeDir).statePath);
+  const installed = (state?.components ?? []).some((entry) => entry.id === componentId);
+  if (!installed) {
+    throw new Error(
+      `Component "${componentId}" is not installed in Kairo state. Run "${formatCliCommand(`install --components ${componentId}`)}" first.`
+    );
+  }
+  return resolveComponent(componentId);
+}
+
+function requireConfiguredComponent(componentId) {
+  const providerId = COMPONENT_PROVIDERS[componentId];
+  if (!providerId) {
+    throw new Error(
+      `components configure/verify/rollback supports: ${Object.keys(COMPONENT_PROVIDERS).join(", ")} (got "${componentId}").`
+    );
+  }
+  return providerId;
+}
+
+export async function runComponentsConfigure(options) {
+  const componentId = options.componentId;
+  const providerId = requireConfiguredComponent(componentId);
+  ensureIntegrationProvidersRegistered();
+  const homeDir = resolveHomeDir();
+  await assertComponentInstalled(componentId, { homeDir });
+  const provider = options.provider ?? requireIntegrationProvider(providerId);
+  const context = await buildProviderContext(options, { homeDir, componentId });
+  const result = await provider.apply(context);
+
+  if (componentId === "sdd-core" && result.receipt && !result.dryRun && !result.cancelled) {
+    if (result.receipt.ok || result.receipt.partial) {
+      await persistSddReceiptState(homeDir, result.receipt);
+    }
+  }
+
+  if (options.json) {
+    printJson(result);
+    if (isConfigureFailure(result)) process.exitCode = 1;
+    return result;
+  }
+
+  if (componentId === "sdd-core") printSddConfigureHuman(result);
+  else printEngramConfigureHuman(result);
+  if (isConfigureFailure(result)) process.exitCode = 1;
+  return result;
+}
+
+export async function runComponentsVerify(options) {
+  const componentId = options.componentId;
+  const providerId = requireConfiguredComponent(componentId);
+  ensureIntegrationProvidersRegistered();
+  const homeDir = resolveHomeDir();
+  await assertComponentInstalled(componentId, { homeDir });
+  const provider = requireIntegrationProvider(providerId);
+  const context = await buildProviderContext(options, { homeDir, componentId });
+  const result = await provider.verify(context);
+
+  if (options.json) {
+    printJson(result);
+    if (result.ok === false) process.exitCode = 1;
+    return result;
+  }
+
+  if (componentId === "sdd-core") printSddVerifyHuman(result);
+  else printEngramConfigureHuman(result);
+  if (result.ok === false) process.exitCode = 1;
+  return result;
+}
+
+export async function runComponentsRollback(options) {
+  const componentId = options.componentId;
+  const providerId = requireConfiguredComponent(componentId);
+  if (!options.receiptId) {
+    throw new Error(
+      `Missing receipt id. Use: ${formatCliCommand(`components rollback ${componentId} --receipt <id>`)}`
+    );
+  }
+
+  ensureIntegrationProvidersRegistered();
+  const homeDir = resolveHomeDir();
+  await assertComponentInstalled(componentId, { homeDir });
+  const provider = options.provider ?? requireIntegrationProvider(providerId);
+  const state = componentId === "sdd-core"
+    ? await readGlobalState(harnessHomePaths(homeDir).statePath)
+    : null;
+  const result = await provider.rollback({
+    receiptId: options.receiptId,
+    homeDir,
+    dryRun: Boolean(options.dryRun),
+    yes: Boolean(options.yes),
+    json: Boolean(options.json),
+    interactive: null,
+    personaAgentIds: state?.sdd?.personaAgentIds ?? []
+  });
+
+  if (
+    componentId === "sdd-core"
+    && !result.dryRun && !result.cancelled && !result.blocked
+    && hasSuccessfulSddRollbackMutations(result.actions)
+  ) {
+    await reconcileSddRollbackState(homeDir, result);
+  }
+
+  if (options.json) {
+    printJson(result);
+    if (!result.ok && !result.cancelled) process.exitCode = 1;
+    return result;
+  }
+
+  console.log(formatCliCommand(`components rollback ${componentId}`));
+  console.log(`Receipt: ${result.receiptId}`);
+  if (result.cancelled) {
+    console.log("Cancelled.");
+    return result;
+  }
+  for (const action of result.actions ?? []) {
+    console.log(`  ${action.action.padEnd(8)} ${action.path ?? "persona"}${action.reason ? ` — ${action.reason}` : ""}`);
+  }
+  console.log(result.ok ? "Rollback complete." : "Rollback finished with skips/errors.");
+  if (!result.ok) process.exitCode = 1;
+  return result;
+}
+
+async function buildProviderContext(options, { homeDir, componentId }) {
+  const detectedAgentIds = detectInstalledAdapters({ homeDir });
+  const base = {
+    requestedAgentIds: options.adapters,
+    detectedAgentIds,
+    homeDir,
+    dryRun: Boolean(options.dryRun),
+    yes: Boolean(options.yes),
+    json: Boolean(options.json),
+    interactive: null
+  };
+  if (componentId !== "sdd-core") return base;
+
+  const state = await readGlobalState(harnessHomePaths(homeDir).statePath);
+  const trackedFiles = Object.fromEntries(
+    (state?.sdd?.files ?? []).map((file) => [file.destinationPath, file.hash])
+  );
+  return {
+    ...base,
+    packageRoot: options.packageRoot ?? DEFAULT_PACKAGE_ROOT,
+    persona: options.persona ?? state?.sdd?.persona ?? "off",
+    personaAgentIds: state?.sdd?.personaAgentIds ?? [],
+    trackedFiles
+  };
+}
+
+async function persistSddReceiptState(homeDir, receipt) {
+  const paths = harnessHomePaths(homeDir);
+  const state = (await readGlobalState(paths.statePath)) ?? {};
+  await writeGlobalState(paths.statePath, recordSddMaterialization(state, { receipt }));
+}
+
+async function reconcileSddRollbackState(homeDir, result) {
+  const paths = harnessHomePaths(homeDir);
+  const state = (await readGlobalState(paths.statePath)) ?? {};
+  const receipt = await loadSddReceipt(result.receiptId, { homeDir });
+  await writeGlobalState(paths.statePath, reconcileSddStateAfterRollback(state, {
+    receipt, actions: result.actions ?? []
+  }));
+}
+
+function isConfigureFailure(result) {
+  return Boolean(result.blocked || (result.receipt && !result.receipt.ok));
+}
+
+export function buildEngramIntegrationChecks(inspection) {
+  const checks = [];
+  const binary = inspection.binary;
+  const binaryStatus = binary.status === ENGRAM_INTEGRATION_STATUS.AVAILABLE
+    || binary.status === ENGRAM_INTEGRATION_STATUS.CONFIGURED
+    || binary.status === ENGRAM_INTEGRATION_STATUS.UNCONFIGURED
+    ? "ok"
+    : "warning";
+
+  checks.push({
+    name: "engram:binary",
+    status: binaryStatus,
+    category: "integration",
+    componentId: "engram-memory",
+    detail: binary.path
+      ? `Engram ${binary.version ?? "unknown"} at ${binary.path} (${binary.status}).${binary.guidance ? ` ${binary.guidance}` : ""}`
+      : (binary.guidance ?? "Engram binary missing.")
+  });
+
+  for (const agent of inspection.agents ?? []) {
+    const status = agent.status === ENGRAM_INTEGRATION_STATUS.CONFIGURED
+      ? "ok"
+      : "warning";
+    checks.push({
+      name: `engram:agent:${agent.id}`,
+      status,
+      category: "integration",
+      componentId: "engram-memory",
+      detail: `${agent.id} → ${agent.slug}: ${agent.status} (config evidence only; not runtime-active).`
+    });
+  }
+
+  return checks;
+}
+
+export function buildSddIntegrationChecks(verification) {
+  const summary = verification.summary ?? {};
+  const persona = verification.persona ?? {};
+  return [
+    {
+      name: "sdd-core:skills",
+      status: verification.status === SDD_HEALTH.CONFIGURED ? "ok" : "warning",
+      category: "integration", componentId: "sdd-core",
+      detail: `SDD skills ${verification.status}: configured=${summary.configured ?? 0}, missing=${summary.missing ?? 0}, drifted=${summary.drifted ?? 0}, conflict=${summary.conflict ?? 0} (disk presence ≠ runtime active).`
+    },
+    {
+      name: "sdd-core:persona",
+      status: persona.status === "configured" || persona.status === "off" ? "ok" : "warning",
+      category: "integration", componentId: "sdd-core",
+      detail: `SDD persona ${persona.status ?? "off"}: active=${Boolean(persona.personaActive)} (state alone ≠ runtime active).`
+    }
+  ];
+}
+
+function printEngramConfigureHuman(result) {
+  console.log(formatCliCommand("components configure engram-memory"));
+  if (result.binary) {
+    console.log(`Binary: ${result.binary.path ?? "missing"} (${result.binary.version ?? "n/a"}, ${result.binary.status})`);
+  }
+  if (result.guidance) console.log(`Guidance: ${result.guidance}`);
+  for (const action of result.actions ?? []) {
+    console.log(`  ${action.action.padEnd(8)} ${action.agentId} (${action.slug})`);
+  }
+  if (result.dryRun) {
+    console.log("Dry-run only — no setup executed.");
+    return;
+  }
+  if (result.cancelled) {
+    console.log("Cancelled.");
+    return;
+  }
+  if (result.receipt) {
+    console.log(`Receipt: ${result.receipt.id}${result.receipt.partial ? " (partial)" : ""}`);
+    console.log(`Status: ${result.receipt.status}`);
+    if (result.receipt.status === ENGRAM_INTEGRATION_STATUS.RESTART_REQUIRED) {
+      console.log("Restart the configured agents to load MCP. Kairo does not claim runtime reload.");
+    }
+  }
+}
+
+function printSddConfigureHuman(result) {
+  console.log(formatCliCommand("components configure sdd-core"));
+  console.log(`Persona: ${result.persona ?? "off"}${result.personaActive ? " (active)" : " (off)"}`);
+  const s = result.summary ?? {};
+  console.log(`Plan: create=${s.create ?? 0} noop=${s.noop ?? 0} update=${s.update ?? 0} conflict=${s.conflict ?? 0}`);
+  for (const action of result.actions ?? []) {
+    console.log(`  ${action.action.padEnd(8)} ${action.skillId} → ${action.destinationPath}`);
+  }
+  if (result.dryRun) return void console.log("Dry-run only — no skills materialized.");
+  if (result.cancelled) return void console.log("Cancelled.");
+  if (result.blocked) return void console.log(`Blocked: ${result.reason ?? "conflicts present"}`);
+  if (result.receipt) {
+    console.log(`Receipt: ${result.receipt.id}${result.receipt.partial ? " (partial)" : ""}`);
+    if (result.sessionRefreshRequired) {
+      console.log("session_refresh_required — restart agents to load skills; Kairo does not claim current sessions already loaded them.");
+    }
+  }
+}
+
+function printSddVerifyHuman(result) {
+  console.log(formatCliCommand("components verify sdd-core"));
+  const s = result.summary ?? {};
+  console.log(`Status: ${result.status}`);
+  console.log(`Summary: configured=${s.configured ?? 0} missing=${s.missing ?? 0} drifted=${s.drifted ?? 0} conflict=${s.conflict ?? 0}`);
+  for (const finding of result.findings ?? []) {
+    console.log(`  ${finding.status.padEnd(10)} ${finding.skillId}${finding.drift ? ` (${finding.drift})` : ""} → ${finding.destinationPath}`);
+  }
+}

package/src/global/component-manifest.js

@@ -0,0 +1,214 @@
+/** Component Manifest v2 — contract + validation. V1 catalogs normalize in-memory. */
+
+import { normalizeIntegrationMetadata } from "./integrations/provider-contract.js";
+
+export const COMPONENT_MANIFEST_SCHEMA_VERSION = 2;
+export const COMPONENT_KINDS = Object.freeze(["component"]);
+export const COMPONENT_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+export const COMPONENT_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+export const CAPABILITY_ID_PATTERN = /^[a-z][a-z0-9.-]*$/;
+export const HEALTH_CHECK_TYPES = Object.freeze(["assets", "drift", "integration"]);
+
+export function normalizeCatalogDocument(document, {
+  source = "bundled",
+  bundledIds = [],
+  requireDefaultEnabled = source === "bundled"
+} = {}) {
+  if (!isObject(document)) throw new Error("Component catalog must be a JSON object.");
+  const schemaVersion = resolveSchemaVersion(document);
+  if (!Array.isArray(document.components)) {
+    throw new Error("Component catalog must declare a components array.");
+  }
+  const components = document.components.map((entry, index) =>
+    normalizeManifestEntry(entry, { source, requireDefaultEnabled, index })
+  );
+  validateCatalogGraph(components, { bundledIds, source });
+  return { schemaVersion, components };
+}
+
+export function normalizeManifestEntry(entry, {
+  source = "bundled",
+  requireDefaultEnabled = false,
+  index = null
+} = {}) {
+  if (!isObject(entry)) throw new Error(entryError(index, entry?.id, "must be an object."));
+  for (const field of ["id", "label", "version", "assetFiles"]) {
+    if (entry[field] === undefined) throw new Error(entryError(index, entry.id, `is missing "${field}".`));
+  }
+  if (requireDefaultEnabled && entry.defaultEnabled === undefined) {
+    throw new Error(entryError(index, entry.id, 'is missing "defaultEnabled".'));
+  }
+
+  const id = match(entry.id, COMPONENT_ID_PATTERN)
+    ? entry.id
+    : fail(entryError(index, entry.id, `has invalid id "${entry.id}". Use lowercase letters, digits, and hyphens.`));
+  const label = nonEmpty(entry.label, id, "label");
+  const version = match(entry.version, COMPONENT_VERSION_PATTERN)
+    ? entry.version
+    : fail(`Component "${id}" has invalid version "${entry.version}". Use semver (e.g. 1.0.0).`);
+  const kind = entry.kind === undefined
+    ? "component"
+    : (COMPONENT_KINDS.includes(entry.kind) ? entry.kind : fail(`Component "${id}" has invalid kind "${entry.kind}". Use: ${COMPONENT_KINDS.join(", ")}.`));
+
+  const normalized = {
+    schemaVersion: COMPONENT_MANIFEST_SCHEMA_VERSION,
+    id,
+    kind,
+    label,
+    version,
+    defaultEnabled: Boolean(requireDefaultEnabled ? entry.defaultEnabled : (entry.defaultEnabled ?? false)),
+    capabilities: idList(entry.capabilities, id, "capabilities", CAPABILITY_ID_PATTERN),
+    dependencies: idList(entry.dependencies, id, "dependencies", COMPONENT_ID_PATTERN),
+    healthChecks: healthChecks(entry.healthChecks, id),
+    assetFiles: assets(entry.assetFiles, id),
+    adapterHints: hints(entry.adapterHints, id),
+    integration: normalizeIntegrationMetadata(entry.integration, { componentId: id, source })
+  };
+
+  if (source === "workspace" && entry.instructions != null) {
+    if (typeof entry.instructions !== "string") fail(`Component "${id}" instructions must be a string.`);
+    normalized.instructions = entry.instructions;
+  }
+  return normalized;
+}
+
+export function validateCatalogGraph(components, { bundledIds = [], source = "bundled" } = {}) {
+  const seen = new Set();
+  const ids = new Set(components.map((c) => c.id));
+  for (const component of components) {
+    if (seen.has(component.id)) fail(`Duplicate component id "${component.id}".`);
+    seen.add(component.id);
+    if (source === "workspace" && bundledIds.includes(component.id)) {
+      fail(`Workspace component "${component.id}" conflicts with a bundled component.`);
+    }
+    for (const dependency of component.dependencies) {
+      if (dependency === component.id) fail(`Component "${component.id}" cannot depend on itself.`);
+      if (!ids.has(dependency) && !bundledIds.includes(dependency)) {
+        fail(`Component "${component.id}" depends on unknown component "${dependency}".`);
+      }
+    }
+  }
+  const cycle = detectDependencyCycles(components);
+  if (cycle) fail(`Component dependency cycle detected: ${cycle.join(" -> ")}.`);
+}
+
+export function detectDependencyCycles(components) {
+  const graph = new Map(components.map((c) => [c.id, c.dependencies]));
+  const visiting = new Set();
+  const visited = new Set();
+  const stack = [];
+  for (const id of graph.keys()) {
+    const cycle = visit(id);
+    if (cycle) return cycle;
+  }
+  return null;
+
+  function visit(id) {
+    if (visited.has(id)) return null;
+    if (visiting.has(id)) return [...stack.slice(stack.indexOf(id)), id];
+    visiting.add(id);
+    stack.push(id);
+    for (const dependency of graph.get(id) ?? []) {
+      if (!graph.has(dependency)) continue;
+      const cycle = visit(dependency);
+      if (cycle) return cycle;
+    }
+    stack.pop();
+    visiting.delete(id);
+    visited.add(id);
+    return null;
+  }
+}
+
+export function assertSafeAssetPath(assetFile, componentId) {
+  if (typeof assetFile !== "string" || !assetFile) fail(`Component "${componentId}" has an invalid asset path.`);
+  if (assetFile.startsWith("/") || assetFile.includes("\\") || assetFile.includes("..")) {
+    fail(`Component "${componentId}" asset "${assetFile}" must be a relative path without "..".`);
+  }
+  if (assetFile.endsWith("/")) fail(`Component "${componentId}" asset "${assetFile}" must reference a file.`);
+  return assetFile;
+}
+
+function resolveSchemaVersion(document) {
+  if (document.schemaVersion === undefined) return 1;
+  const version = document.schemaVersion;
+  if (typeof version !== "number" || !Number.isInteger(version) || version < 1 || version > COMPONENT_MANIFEST_SCHEMA_VERSION) {
+    fail(`Unsupported component catalog schemaVersion "${version}".`);
+  }
+  return version;
+}
+
+function assets(assetFiles, id) {
+  if (!Array.isArray(assetFiles) || assetFiles.length === 0) fail(`Component "${id}" must declare at least one asset file.`);
+  return unique(assetFiles.map((asset) => assertSafeAssetPath(asset, id)), id, "asset");
+}
+
+function idList(value, id, field, pattern) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) fail(`Component "${id}" ${field} must be an array.`);
+  return unique(value.map((item) => {
+    if (typeof item !== "string" || !pattern.test(item)) fail(`Component "${id}" has invalid ${field} entry "${item}".`);
+    return item;
+  }), id, field);
+}
+
+function healthChecks(value, id) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) fail(`Component "${id}" healthChecks must be an array.`);
+  const seen = new Set();
+  return value.map((check) => {
+    if (!isObject(check)) fail(`Component "${id}" healthChecks entries must be objects.`);
+    if (typeof check.id !== "string" || !CAPABILITY_ID_PATTERN.test(check.id)) {
+      fail(`Component "${id}" healthCheck has invalid id "${check.id}".`);
+    }
+    if (typeof check.type !== "string" || !HEALTH_CHECK_TYPES.includes(check.type)) {
+      fail(`Component "${id}" healthCheck "${check.id}" has invalid type "${check.type}".`);
+    }
+    if (seen.has(check.id)) fail(`Component "${id}" declares duplicate healthCheck "${check.id}".`);
+    seen.add(check.id);
+    return { id: check.id, type: check.type, optional: Boolean(check.optional) };
+  });
+}
+
+function hints(value, id) {
+  if (value === undefined) return {};
+  if (!isObject(value)) fail(`Component "${id}" adapterHints must be an object.`);
+  const normalized = {};
+  for (const [key, hint] of Object.entries(value)) {
+    if (typeof hint !== "string") fail(`Component "${id}" adapterHints.${key} must be a string.`);
+    normalized[key] = hint;
+  }
+  return normalized;
+}
+
+function unique(items, id, field) {
+  const seen = new Set();
+  const out = [];
+  for (const item of items) {
+    if (seen.has(item)) fail(`Component "${id}" declares duplicate ${field} entry "${item}".`);
+    seen.add(item);
+    out.push(item);
+  }
+  return out;
+}
+
+function nonEmpty(value, id, field) {
+  if (typeof value !== "string" || !value.trim()) fail(`Component "${id}" ${field} must be a non-empty string.`);
+  return value.trim();
+}
+
+function match(value, pattern) {
+  return typeof value === "string" && pattern.test(value);
+}
+
+function isObject(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+function entryError(index, id, message) {
+  return `${id ? `Component "${id}"` : `Component catalog entry${index == null ? "" : ` #${index}`}`} ${message}`;
+}
+
+function fail(message) {
+  throw new Error(message);
+}

package/src/global/component-registry.js

@@ -1,5 +1,9 @@
 import { loadComponentCatalog } from "./load-component-catalog.js";
 import { loadWorkspaceComponentCatalog } from "./load-workspace-component-catalog.js";
+import { indexComponentsById, resolveDependencyOrder } from "./component-resolve.js";
+import { ensureIntegrationProvidersRegistered } from "./integrations/index.js";
+
+ensureIntegrationProvidersRegistered();
 
 const BUNDLED_COMPONENTS = loadComponentCatalog();
 
@@ -24,10 +28,16 @@ function formatCatalogEntry(component) {
     id: component.id,
     label: component.label,
     version: component.version,
+    schemaVersion: component.schemaVersion ?? 2,
+    kind: component.kind ?? "component",
     source: component.source ?? "bundled",
     defaultEnabled: component.defaultEnabled,
+    capabilities: [...(component.capabilities ?? [])],
+    dependencies: [...(component.dependencies ?? [])],
+    healthChecks: (component.healthChecks ?? []).map((check) => ({ ...check })),
     assetFiles: [...component.assetFiles],
     adapterHints: Object.keys(component.adapterHints),
+    integration: component.integration ? { ...component.integration } : null,
     instructions: component.instructions ?? null
   };
 }
@@ -69,12 +79,19 @@ export function resolveTargetComponents({
   workspaceRoot = null
 } = {}) {
   if (components != null) {
-    return validateComponentIds(components, { workspaceRoot }).map((id) => resolveComponent(id, { workspaceRoot }));
+    return resolveComponentClosure(components, { workspaceRoot });
   }
 
   if (noDefaultComponents) return [];
 
-  return DEFAULT_COMPONENT_IDS.map((id) => resolveComponent(id, { workspaceRoot }));
+  return resolveComponentClosure(DEFAULT_COMPONENT_IDS, { workspaceRoot });
+}
+
+export function resolveComponentClosure(seedIds, { workspaceRoot = null } = {}) {
+  const catalog = mergeComponents(workspaceRoot);
+  const byId = indexComponentsById(catalog);
+  const validatedSeeds = validateComponentIds(seedIds, { workspaceRoot });
+  return resolveDependencyOrder(validatedSeeds, byId);
 }
 
 export function buildComponentStateEntries(components, adapters) {

package/src/global/component-resolve.js

@@ -0,0 +1,51 @@
+/**
+ * Deterministic component dependency resolution (deps first, no duplicates).
+ */
+
+export function resolveDependencyOrder(seedIds, componentsById) {
+  const seeds = uniqueIds(seedIds);
+  const selected = new Set();
+  const visiting = new Set();
+  const ordered = [];
+
+  for (const seedId of seeds) {
+    visit(seedId);
+  }
+
+  return ordered;
+
+  function visit(id) {
+    if (selected.has(id)) return;
+    if (visiting.has(id)) {
+      throw new Error(`Component dependency cycle detected while resolving "${id}".`);
+    }
+
+    const component = componentsById.get(id);
+    if (!component) {
+      throw new Error(`Unknown component "${id}".`);
+    }
+
+    visiting.add(id);
+    for (const dependency of component.dependencies ?? []) {
+      visit(dependency);
+    }
+    visiting.delete(id);
+    selected.add(id);
+    ordered.push(component);
+  }
+}
+
+export function indexComponentsById(components) {
+  return new Map(components.map((component) => [component.id, component]));
+}
+
+function uniqueIds(ids) {
+  const seen = new Set();
+  const unique = [];
+  for (const id of ids) {
+    if (seen.has(id)) continue;
+    seen.add(id);
+    unique.push(id);
+  }
+  return unique;
+}

package/src/global/components/sdd-core.js

@@ -1,8 +1,10 @@
 import { join } from "node:path";
+import { SDD_PERSONA_GATE } from "../integrations/sdd-persona.js";
 
 export function buildSddCoreManagedSection(context, adapter, catalogEntry) {
   const baseDir = join(context.componentsDir, "sdd-core");
   const adapterNote = catalogEntry?.adapterHints?.[adapter.id] ?? null;
+  const teachingPath = join(baseDir, "personas", "teaching.md");
 
   return [
     "### SDD Core",
@@ -10,6 +12,10 @@ export function buildSddCoreManagedSection(context, adapter, catalogEntry) {
     `- Workflow: ${join(baseDir, "workflow.md")}`,
     `- Spec sizing: ${join(baseDir, "spec-sizing.md")}`,
     `- Handoff rules: ${join(baseDir, "handoff.md")}`,
+    `- Canonical skills: ${join(baseDir, "skills")}`,
+    `- Teaching persona: load ${teachingPath} only if adapter id "${adapter.id}" is listed in ${context.paths.statePath} → ${SDD_PERSONA_GATE}.`,
+    "- Phase skills: sdd-init, sdd-explore, sdd-propose, sdd-spec, sdd-design, sdd-tasks, sdd-apply, sdd-verify, sdd-archive.",
+    "- Teaching persona affects explanations only; never code, docs, commits, or PRs.",
     "- Classify work as basic, standard, or complex before implementing.",
     "- No significant feature without a spec; no bug fix without a failing test first.",
     adapterNote