@kontourai/flow-agents 2.3.0 → 3.0.0

package/src/cli.ts

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { basename } from "node:path";
 import { main as effectiveBacklogSettings } from "./cli/effective-backlog-settings.js";
+import { main as effectiveAssignmentProviderSettings } from "./cli/effective-assignment-provider-settings.js";
+import { main as assignmentProvider } from "./cli/assignment-provider.js";
 import { main as consoleLearningProjection } from "./cli/console-learning-projection.js";
 import { main as kit } from "./cli/kit.js";
 import { main as fixtureRetirementAudit } from "./cli/fixture-retirement-audit.js";
@@ -25,6 +27,8 @@ const availableCommands = new Map<string, (argv: string[]) => number | Promise<n
   ["build-bundles", () => buildBundles()],
   ["console-learning-projection", consoleLearningProjection],
   ["context-map", contextMap],
+  ["assignment-provider", assignmentProvider],
+  ["effective-assignment-provider-settings", effectiveAssignmentProviderSettings],
   ["effective-backlog-settings", effectiveBacklogSettings],
   ["fixture-retirement-audit", fixtureRetirementAudit],
   ["kit", kit],
@@ -48,6 +52,8 @@ const aliases = new Map<string, string>([
   ["flow-agents-build-bundles", "build-bundles"],
   ["flow-agents-console-learning-projection", "console-learning-projection"],
   ["flow-agents-context-map", "context-map"],
+  ["flow-agents-assignment-provider", "assignment-provider"],
+  ["flow-agents-effective-assignment-provider-settings", "effective-assignment-provider-settings"],
   ["flow-agents-effective-backlog-settings", "effective-backlog-settings"],
   ["flow-agents-fixture-retirement-audit", "fixture-retirement-audit"],
   ["flow-agents-kit", "kit"],

package/src/flow-kit/validate.ts

@@ -10,6 +10,72 @@ const EXTENSION_ASSET_CLASSES = ["skills", "docs", "adapters", "evals", "assets"
 const CORE_CONTAINER_FIELDS = new Set(["schema_version", "id", "name", "description", "product_name", "flows"]);
 const AGENT_EXTENSION_CLASSES = new Set(["skills", "docs", "adapters", "evals", "assets"]);
 
+// Flow Agents-recognized metadata fields that are neither core container fields nor
+// agent-extension asset classes. Recognized here so they are never misreported as
+// unknown third-party extension namespaces. `dependencies` declares cross-kit skill
+// dependencies (extension-layer ownership; see docs/adr/0019-kit-dependency-ownership.md).
+const KNOWN_METADATA_FIELDS = new Set(["dependencies"]);
+
+export interface KitDependencyEntry {
+  kit_id: string;
+  reason?: string;
+}
+
+/**
+ * Parse and shape-validate a kit manifest's `dependencies` field (Flow Agents
+ * extension-layer metadata; see docs/adr/0019-kit-dependency-ownership.md).
+ *
+ * Shape rules:
+ *  - `dependencies` (if present) must be an array.
+ *  - each entry must be an object with a `kit_id` string matching ^[a-z][a-z0-9-]*$.
+ *  - `kit_id` must not equal the declaring kit's own id (no self-reference).
+ *  - no duplicate `kit_id` across entries.
+ *  - `reason` is an optional string.
+ *
+ * Returns the parsed entries plus any shape errors (empty errors = valid). This is
+ * a sibling shape check, not a member of the file-path-oriented EXTENSION_ASSET_CLASSES
+ * loop, because dependency entries have no `path`/file to check.
+ */
+export function parseKitDependencies(manifest: Record<string, unknown>, manifestPath: string): { entries: KitDependencyEntry[]; errors: string[] } {
+  const entries: KitDependencyEntry[] = [];
+  const errors: string[] = [];
+  const raw = manifest.dependencies;
+  if (raw === undefined) return { entries, errors };
+  if (!Array.isArray(raw)) {
+    errors.push(`${manifestPath}: .dependencies must be a list`);
+    return { entries, errors };
+  }
+  const ownId = typeof manifest.id === "string" ? manifest.id : "";
+  const seen = new Set<string>();
+  raw.forEach((entry, index) => {
+    if (typeof entry !== "object" || entry === null) {
+      errors.push(`${manifestPath}: dependencies[${index}] must be an object`);
+      return;
+    }
+    const record = entry as Record<string, unknown>;
+    const kitId = record.kit_id;
+    if (typeof kitId !== "string" || !/^[a-z][a-z0-9-]*$/.test(kitId)) {
+      errors.push(`${manifestPath}: dependencies[${index}].kit_id must be a kebab-case kit id (^[a-z][a-z0-9-]*$)`);
+      return;
+    }
+    if (ownId && kitId === ownId) {
+      errors.push(`${manifestPath}: dependencies[${index}].kit_id must not reference the declaring kit itself ('${kitId}')`);
+      return;
+    }
+    if (seen.has(kitId)) {
+      errors.push(`${manifestPath}: dependencies[${index}].kit_id duplicates '${kitId}'`);
+      return;
+    }
+    seen.add(kitId);
+    if (record.reason !== undefined && typeof record.reason !== "string") {
+      errors.push(`${manifestPath}: dependencies[${index}].reason must be a string when present`);
+    }
+    const reason = typeof record.reason === "string" ? record.reason : undefined;
+    entries.push({ kit_id: kitId, ...(reason ? { reason } : {}) });
+  });
+  return { entries, errors };
+}
+
 export type KitTargetConsumer =
   | "flow"
   | "flow-agents"
@@ -167,7 +233,7 @@ export async function deriveKitTargets(manifest: Record<string, unknown>, kitDir
   // Detect third-party extension namespaces: top-level keys that are neither
   // core fields nor Flow Agents extension classes.
   const thirdPartyExtensions: string[] = Object.keys(manifest)
-    .filter((key) => !CORE_CONTAINER_FIELDS.has(key) && !AGENT_EXTENSION_CLASSES.has(key))
+    .filter((key) => !CORE_CONTAINER_FIELDS.has(key) && !AGENT_EXTENSION_CLASSES.has(key) && !KNOWN_METADATA_FIELDS.has(key))
     .sort();
 
   const targets: KitTargetConsumer[] = [];
@@ -247,6 +313,13 @@ export async function validateKitRepository(kitDir: string): Promise<string[]> {
       }
     });
   }
+
+  // Flow Agents metadata: cross-kit dependency declarations (extension-layer;
+  // see docs/adr/0019-kit-dependency-ownership.md). Shape-only here — presence is
+  // checked separately (non-blocking at install, hard error at activation).
+  const depResult = parseKitDependencies(manifest, manifestPath);
+  for (const err of depResult.errors) errors.push(err);
+
   return errors;
 }
 

package/src/index.ts

@@ -18,13 +18,17 @@ import { loadJson as _loadJson, writeJson as _writeJson } from "./cli/workflow-s
 
 export {
   defaultArtifactRootForRead,
+  defaultCodexHome,
   defaultTelemetryDirForRead,
   defaultTelemetryDirsForRead,
+  durableFlowAgentsRoot,
+  durableInstallRecordPath,
+  DURABLE_FLOW_AGENTS_DIR,
+  FLOW_AGENTS_RUNTIME_DIR,
+  FLOW_AGENTS_RUNTIME_SUBDIR,
   firstExistingPath,
   flowAgentsArtifactRoot,
   KONTOURAI_DIR,
-  legacyFlowAgentsArtifactRoot,
-  LEGACY_FLOW_AGENTS_DIR,
   legacyTelemetryDataDir,
   LEGACY_TELEMETRY_DIR,
   telemetryDataDir,

package/src/lib/flow-resolver.ts

@@ -20,9 +20,9 @@ import * as path from "node:path";
 //
 // Both kitId and flowName originate from agent-writable sources (active_flow_id
 // in current.json, and FLOW_AGENTS_FLOW_DEFS_DIR set by the runtime). A crafted
-// value like "builder.../../../.flow-agents/slug/fake-flow" produces:
+// value like "builder.../../../.kontourai/flow-agents/slug/fake-flow" produces:
 //   kitId = "builder"
-//   flowName = "../../../.flow-agents/slug/fake-flow"
+//   flowName = "../../../.kontourai/flow-agents/slug/fake-flow"
 // which resolves OUTSIDE kits/ via path.join traversal.
 //
 // SLUG_RE closes this: it rejects any value containing path separators, dots,
@@ -36,12 +36,23 @@ import * as path from "node:path";
 const SLUG_RE = /^[a-zA-Z0-9_-]+$/;
 
 /**
- * Returns true when the given resolved absolute path falls within a .flow-agents
- * directory (an agent-writable area). Used to reject FLOW_AGENTS_FLOW_DEFS_DIR
+ * Returns true when the given resolved absolute path falls within a Flow Agents
+ * runtime artifact directory (an agent-writable area). Used to reject FLOW_AGENTS_FLOW_DEFS_DIR
  * overrides that point into agent-controlled storage.
  */
+function hasAgentWritableRuntimeSegment(resolvedDir: string): boolean {
+  const parts = resolvedDir.split(path.sep);
+  if (parts.includes(".flow-agents")) return true;
+  return parts.some((part, index) => part === ".kontourai" && parts[index + 1] === "flow-agents");
+}
+
 function isAgentWritableDir(resolvedDir: string): boolean {
-  return resolvedDir.split(path.sep).includes(".flow-agents");
+  if (hasAgentWritableRuntimeSegment(resolvedDir)) return true;
+  try {
+    return hasAgentWritableRuntimeSegment(fs.realpathSync.native(resolvedDir));
+  } catch {
+    return false;
+  }
 }
 
 /**
@@ -49,11 +60,11 @@ function isAgentWritableDir(resolvedDir: string): boolean {
  *
  * Returns the validated absolute file path, or null when:
  *  - kitId or flowName contains chars outside SLUG_RE (rejects traversal)
- *  - FLOW_AGENTS_FLOW_DEFS_DIR resolves into a .flow-agents directory
+ *  - FLOW_AGENTS_FLOW_DEFS_DIR resolves into a runtime artifact directory
  *  - The resolved path escapes the expected root (belt-and-suspenders)
  *
- * When the override is unsafe (points into .flow-agents), falls back silently
- * to the repoRoot/kits/ path so the resolver still works for legit flows.
+ * When the override is unsafe, it is ignored and the resolver uses the
+ * canonical repoRoot/kits/ source for legitimate flows.
  */
 export function resolveFlowFilePath(
   kitId: string,
@@ -72,8 +83,8 @@ export function resolveFlowFilePath(
   if (override) {
     const resolvedOverride = path.resolve(override);
     if (isAgentWritableDir(resolvedOverride)) {
-      // Override targets an agent-writable .flow-agents path — reject it and
-      // fall back to the kit root.  The session will resolve the real kit flow.
+      // Override targets an agent-writable runtime path; ignore it and use
+      // the canonical kit root. The session will resolve the real kit flow.
       expectedRoot = path.resolve(repoRoot, "kits");
       flowFilePath = path.join(repoRoot, "kits", kitId, "flows", `${flowName}.flow.json`);
     } else {
@@ -95,7 +106,19 @@ export function resolveFlowFilePath(
     return null; // traversal still detected — paranoid fallback
   }
 
-  return resolvedPath;
+  // If the file exists, resolve final symlinks before returning a readable path.
+  // `readFileSync` follows symlinks; this keeps lexical containment from turning
+  // into an out-of-root file read through a symlinked FlowDefinition.
+  try {
+    const realExpectedRoot = fs.existsSync(expectedRoot) ? fs.realpathSync.native(expectedRoot) : expectedRoot;
+    const realPath = fs.realpathSync.native(resolvedPath);
+    if (!realPath.startsWith(realExpectedRoot + path.sep) && realPath !== realExpectedRoot) {
+      return null;
+    }
+    return realPath;
+  } catch {
+    return resolvedPath;
+  }
 }
 
 // ─── Public types ─────────────────────────────────────────────────────────────
@@ -118,6 +141,8 @@ export type ActiveFlowStep = {
   stepId: string;
   gateId: string;
   gateExpects: GateExpectation[];
+  /** When resolved through a parent step's uses_flow edge, names the child FlowDefinition that owns the gate. */
+  sourceFlowId?: string;
 };
 
 /** Shape of a gate entry in the FlowDefinition JSON. */
@@ -138,10 +163,38 @@ type FlowDefinition = {
    *  (e.g. "execution") to step ids (e.g. "execute") so advance-state can write active_step_id
    *  without hardcoding any vocabulary in the core. */
   phase_map?: Record<string, string>;
-  steps?: Array<{ id: string; next: string | null }>;
+  steps?: Array<{ id: string; next: string | null; uses_flow?: string }>;
   gates?: Record<string, FlowGate>;
+  /** Optional claim types or expectation ids this flow intentionally exposes to parent/composed flows. */
+  exports?: string[];
 };
 
+type InternalActiveFlowStep = ActiveFlowStep & { flowExports?: string[] };
+
+function flowIdParts(flowId: string): { kitId: string; flowName: string } | null {
+  if (!flowId) return null;
+  const dotIdx = flowId.indexOf(".");
+  if (dotIdx < 1) return null;
+  const kitId = flowId.slice(0, dotIdx);
+  const flowName = flowId.slice(dotIdx + 1);
+  if (!kitId || !flowName) return null;
+  return { kitId, flowName };
+}
+
+function readFlowDefinition(flowId: string, repoRoot: string): FlowDefinition | null {
+  const parts = flowIdParts(flowId);
+  if (!parts) return null;
+  const flowFilePath = resolveFlowFilePath(parts.kitId, parts.flowName, flowId, repoRoot);
+  if (!flowFilePath) return null;
+
+  try {
+    const raw = fs.readFileSync(flowFilePath, "utf8");
+    return JSON.parse(raw) as FlowDefinition;
+  } catch {
+    return null; // ENOENT, permission error, or parse error → fail-open
+  }
+}
+
 /**
  * Resolve the gate expects[] for a specific (flowId, stepId) pair.
  *
@@ -152,38 +205,69 @@ type FlowDefinition = {
  * @returns ActiveFlowStep with the matched gate's expects[], or null on any error.
  */
 export function resolveFlowStep(flowId: string, stepId: string, repoRoot: string): ActiveFlowStep | null {
+  const resolved = resolveFlowStepInternal(flowId, stepId, repoRoot, new Set<string>());
+  if (!resolved) return null;
+  const { flowExports: _flowExports, ...publicStep } = resolved;
+  return publicStep;
+}
+
+function expectationExportKeys(expectation: GateExpectation): string[] {
+  const keys: string[] = [];
+  if (typeof expectation.id === "string" && expectation.id) keys.push(expectation.id);
+  const claimType = expectation.bundle_claim?.claimType;
+  if (typeof claimType === "string" && claimType) keys.push(claimType);
+  return keys;
+}
+
+function exportedExpectations(expectations: GateExpectation[], exportsList: unknown): GateExpectation[] | null {
+  if (!Array.isArray(exportsList)) return null;
+  const exported = new Set(exportsList.filter((item): item is string => typeof item === "string" && item.length > 0));
+  const allowed = expectations.filter((expectation) => expectationExportKeys(expectation).some((key) => exported.has(key)));
+  return allowed.length === expectations.length ? allowed : null;
+}
+
+function resolveFlowStepInternal(flowId: string, stepId: string, repoRoot: string, seen: Set<string>): InternalActiveFlowStep | null {
   if (!flowId || !stepId) return null;
-  const dotIdx = flowId.indexOf(".");
-  if (dotIdx < 1) return null; // flowId must have at least one "." to derive kitId
-  const kitId = flowId.slice(0, dotIdx);
-  // The flow filename is the part after the first "." (e.g. "build" from "builder.build")
-  const flowName = flowId.slice(dotIdx + 1);
-  if (!kitId || !flowName) return null;
+  if (!flowIdParts(flowId)) return null;
 
   // Layer 1 defense: validate stepId too — it is matched against gate.step values but
   // still originates from agent-writable current.json active_step_id.
   if (!SLUG_RE.test(stepId)) return null;
+  const seenKey = `${flowId}:${stepId}`;
+  if (seen.has(seenKey)) return null;
+  seen.add(seenKey);
 
-  // Determine the FlowDefinition file path with slug validation + path containment check.
-  // Returns null for traversal attempts (e.g. flowName = "../../../.flow-agents/fake").
-  const flowFilePath = resolveFlowFilePath(kitId, flowName, flowId, repoRoot);
-  if (!flowFilePath) return null;
+  const flowDef = readFlowDefinition(flowId, repoRoot);
+  if (!flowDef) return null;
 
-  let flowDef: FlowDefinition;
-  try {
-    const raw = fs.readFileSync(flowFilePath, "utf8");
-    flowDef = JSON.parse(raw) as FlowDefinition;
-  } catch {
-    return null; // ENOENT, permission error, or parse error → fail-open
-  }
-
-  if (!flowDef || typeof flowDef !== "object" || !flowDef.gates) return null;
+  if (!flowDef || typeof flowDef !== "object") return null;
 
   // Find the gate whose .step matches stepId.
-  for (const [gateId, gate] of Object.entries(flowDef.gates)) {
-    if (!gate || gate.step !== stepId) continue;
-    const expects = Array.isArray(gate.expects) ? gate.expects : [];
-    return { flowId, stepId, gateId, gateExpects: expects };
+  if (flowDef.gates) {
+    for (const [gateId, gate] of Object.entries(flowDef.gates)) {
+      if (!gate || gate.step !== stepId) continue;
+      const expects = Array.isArray(gate.expects) ? gate.expects : [];
+      return { flowId, stepId, gateId, gateExpects: expects, flowExports: flowDef.exports };
+    }
+  }
+
+  const composedStep = Array.isArray(flowDef.steps)
+    ? flowDef.steps.find((step) => step && step.id === stepId && typeof step.uses_flow === "string" && step.uses_flow.trim())
+    : null;
+  if (composedStep?.uses_flow) {
+    const child = resolveFlowStepInternal(composedStep.uses_flow, stepId, repoRoot, seen);
+    if (child) {
+      const childGateExpects = exportedExpectations(child.gateExpects, child.flowExports);
+      if (!childGateExpects) return null;
+      return {
+        flowId,
+        stepId,
+        gateId: `${child.flowId}:${child.gateId}`,
+        gateExpects: childGateExpects,
+        sourceFlowId: child.flowId,
+        flowExports: flowDef.exports,
+      };
+    }
   }
 
   return null; // no gate matched the given stepId
@@ -205,24 +289,8 @@ export function resolveFlowStep(flowId: string, stepId: string, repoRoot: string
  * @returns Record<string,string> phase→stepId map, or null on absence/error.
  */
 export function resolvePhaseMap(flowId: string, repoRoot: string): Record<string, string> | null {
-  if (!flowId) return null;
-  const dotIdx = flowId.indexOf(".");
-  if (dotIdx < 1) return null;
-  const kitId = flowId.slice(0, dotIdx);
-  const flowName = flowId.slice(dotIdx + 1);
-  if (!kitId || !flowName) return null;
-
-  // Layer 1 defense: same slug validation + path containment as resolveFlowStep.
-  const flowFilePath = resolveFlowFilePath(kitId, flowName, flowId, repoRoot);
-  if (!flowFilePath) return null;
-
-  let flowDef: FlowDefinition;
-  try {
-    const raw = fs.readFileSync(flowFilePath, "utf8");
-    flowDef = JSON.parse(raw) as FlowDefinition;
-  } catch {
-    return null; // ENOENT, permission error, or parse error → fail-open
-  }
+  const flowDef = readFlowDefinition(flowId, repoRoot);
+  if (!flowDef) return null;
 
   if (!flowDef || typeof flowDef !== "object") return null;
   const pm = flowDef.phase_map;
@@ -239,7 +307,7 @@ export function resolvePhaseMap(flowId: string, repoRoot: string): Record<string
  * the nearest ancestor that contains a `kits/` subdirectory. If none is found,
  * falls back to `process.cwd()` so the default "run from repo root" case still works.
  *
- * This is required because the .flow-agents directory can live anywhere (temp dirs,
+ * This is required because the runtime artifact directory can live anywhere (temp dirs,
  * subprojects, CI workspaces) while the kits/ directory is always at the repo root.
  */
 function findRepoRoot(startDir: string): string {
@@ -264,7 +332,7 @@ function findRepoRoot(startDir: string): string {
  * with a fallback to process.cwd(). This handles temp dirs, CI workspaces, and
  * subproject layouts without hardcoding the repo structure.
  *
- * @param flowAgentsDir Path to the .flow-agents directory (contains current.json).
+ * @param flowAgentsDir Path to the runtime artifact root directory (contains current.json).
  * @returns ActiveFlowStep or null when fields are absent or resolution fails.
  */
 export function resolveActiveFlowStep(flowAgentsDir: string): ActiveFlowStep | null {

package/src/lib/local-artifact-root.ts

@@ -1,16 +1,35 @@
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 
 export const KONTOURAI_DIR = ".kontourai";
-export const LEGACY_FLOW_AGENTS_DIR = ".flow-agents";
+export const FLOW_AGENTS_RUNTIME_SUBDIR = "flow-agents";
+export const FLOW_AGENTS_RUNTIME_DIR = `${KONTOURAI_DIR}/${FLOW_AGENTS_RUNTIME_SUBDIR}`;
+export const DURABLE_FLOW_AGENTS_DIR = ".flow-agents";
 export const LEGACY_TELEMETRY_DIR = ".telemetry";
 
+/**
+ * Default Codex home: `$CODEX_HOME` when set, else `~/.codex`.
+ *
+ * This is the Codex CLI's own config/state root and is conceptually
+ * distinct from the Flow Agents global bundle install root (`~/.flow-agents`)
+ * and the durable per-destination install record root
+ * (`DURABLE_FLOW_AGENTS_DIR`, i.e. `.flow-agents`).
+ */
+export function defaultCodexHome(): string {
+  return process.env["CODEX_HOME"] || path.join(os.homedir(), ".codex");
+}
+
 export function flowAgentsArtifactRoot(cwd = process.cwd()): string {
-  return path.resolve(cwd, KONTOURAI_DIR, "flow-agents");
+  return path.resolve(cwd, FLOW_AGENTS_RUNTIME_DIR);
+}
+
+export function durableFlowAgentsRoot(cwd = process.cwd()): string {
+  return path.resolve(cwd, DURABLE_FLOW_AGENTS_DIR);
 }
 
-export function legacyFlowAgentsArtifactRoot(cwd = process.cwd()): string {
-  return path.resolve(cwd, LEGACY_FLOW_AGENTS_DIR);
+export function durableInstallRecordPath(cwd = process.cwd()): string {
+  return path.join(durableFlowAgentsRoot(cwd), "install.json");
 }
 
 export function telemetryDataDir(cwd = process.cwd()): string {
@@ -26,7 +45,7 @@ export function firstExistingPath(candidates: string[]): string {
 }
 
 export function defaultArtifactRootForRead(cwd = process.cwd()): string {
-  return firstExistingPath([flowAgentsArtifactRoot(cwd), legacyFlowAgentsArtifactRoot(cwd)]);
+  return flowAgentsArtifactRoot(cwd);
 }
 
 export function defaultTelemetryDirForRead(cwd = process.cwd()): string {

package/src/lib/workflow-learning-projection.ts

@@ -176,7 +176,7 @@ const KNOWN_CORRECTION_TYPES = new Set<WorkflowLearningCorrectionType>([
   "provider",
   "none",
 ]);
-const SKIPPED_ROOT_ENTRIES = new Set(["archive", "changes", "delivery-history"]);
+const SKIPPED_ROOT_ENTRIES = new Set(["archive", "changes", "delivery-history", "liveness"]);
 const MAX_SIDECAR_BYTES = 1024 * 1024;
 
 export function readWorkflowLearningSources(artifactRoot: string): WorkflowLearningSource[] {
@@ -229,7 +229,7 @@ export function buildWorkflowLearningProjection(
         sourceRef: {
           product: "flow-agents",
           kind: "workflow-learning",
-          id: ".flow-agents/*/learning.json",
+          id: ".kontourai/flow-agents/*/learning.json",
           label: "Local workflow learning sidecars",
         },
       },

package/src/runtime-adapters.ts

@@ -1,6 +1,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { readJson, relPath, writeJson } from "./lib/fs.js";
+import { flowAgentsArtifactRoot } from "./lib/local-artifact-root.js";
+import { parseKitDependencies } from "./flow-kit/validate.js";
 
 export type KitAsset = {
   kit_id: string;
@@ -15,6 +17,12 @@ export type KitAsset = {
 
 export type KitInventory = { assets: KitAsset[]; warnings: string[]; errors: string[] };
 
+/** A cross-kit dependency edge discovered while loading a kit manifest. */
+export type KitDependencyRef = { from_kit_id: string; kit_id: string; reason?: string };
+
+/** The parsed result of a single kit manifest: its id, activatable assets, and declared dependencies. */
+export type LoadedKit = { kit_id: string; assets: KitAsset[]; dependencies: KitDependencyRef[] };
+
 const ASSET_CLASSES = ["flows", "skills", "docs", "adapters", "evals", "assets"];
 
 function assetPath(root: string, value: string): string | null {
@@ -24,24 +32,24 @@ function assetPath(root: string, value: string): string | null {
   return resolved === absRoot || resolved.startsWith(`${absRoot}${path.sep}`) ? resolved : null;
 }
 
-function loadKitAssets(kitRoot: string, sourceKind: string, warnings: string[], errors: string[]): KitAsset[] {
+function loadKitAssets(kitRoot: string, sourceKind: string, warnings: string[], errors: string[]): LoadedKit {
   const manifestPath = path.join(kitRoot, "kit.json");
   if (!fs.existsSync(manifestPath)) {
     errors.push(`${kitRoot}: missing kit.json`);
-    return [];
+    return { kit_id: "", assets: [], dependencies: [] };
   }
   let manifest: Record<string, unknown>;
   try {
     manifest = readJson(manifestPath) as Record<string, unknown>;
   } catch (error) {
     errors.push(`${manifestPath}: ${(error as Error).message}`);
-    return [];
+    return { kit_id: "", assets: [], dependencies: [] };
   }
   const kitId = typeof manifest.id === "string" ? manifest.id : "";
   const kitName = typeof manifest.name === "string" ? manifest.name : kitId;
   if (!kitId) {
     errors.push(`${manifestPath}: missing kit id`);
-    return [];
+    return { kit_id: "", assets: [], dependencies: [] };
   }
   const assets: KitAsset[] = [];
   for (const assetClass of ASSET_CLASSES) {
@@ -78,13 +86,21 @@ function loadKitAssets(kitRoot: string, sourceKind: string, warnings: string[],
       assets.push({ kit_id: kitId, kit_name: kitName, asset_class: assetClass, asset_id: assetId, relative_path: rel, source_path: source, source_kind: sourceKind, description });
     }
   }
-  return assets;
+  // Parse cross-kit dependency declarations (extension-layer metadata; see
+  // docs/adr/0019-kit-dependency-ownership.md). Shape errors surface at
+  // install/inspect/validate time via validateKitRepository; here we only collect
+  // the edges so activation can enforce presence against the full inventory.
+  const dependencies: KitDependencyRef[] = parseKitDependencies(manifest, manifestPath).entries
+    .map((dep) => ({ from_kit_id: kitId, kit_id: dep.kit_id, ...(dep.reason ? { reason: dep.reason } : {}) }));
+  return { kit_id: kitId, assets, dependencies };
 }
 
 export function readKitInventory(sourceRoot: string, dest: string): KitInventory {
   const warnings: string[] = [];
   const errors: string[] = [];
   const assets: KitAsset[] = [];
+  const dependencies: KitDependencyRef[] = [];
+  const presentKitIds = new Set<string>();
   const catalogPath = path.join(sourceRoot, "kits", "catalog.json");
   if (!fs.existsSync(catalogPath)) warnings.push(`${catalogPath}: built-in Kit Catalog not found; skipping built-in kits (this is normal when running outside a flow-agents checkout)`);
   else {
@@ -99,7 +115,12 @@ export function readKitInventory(sourceRoot: string, dest: string): KitInventory
         }
         const kitRoot = assetPath(sourceRoot, rel);
         if (!kitRoot || !fs.existsSync(kitRoot)) warnings.push(`${catalogPath}: kits[${index}].path unavailable: ${rel}`);
-        else assets.push(...loadKitAssets(kitRoot, "builtin", warnings, errors));
+        else {
+          const loaded = loadKitAssets(kitRoot, "builtin", warnings, errors);
+          assets.push(...loaded.assets);
+          dependencies.push(...loaded.dependencies);
+          if (loaded.kit_id) presentKitIds.add(loaded.kit_id);
+        }
       });
     }
   }
@@ -115,10 +136,23 @@ export function readKitInventory(sourceRoot: string, dest: string): KitInventory
         if (typeof id !== "string") return;
         const kitRoot = path.join(dest, "kits", "local", "repositories", id);
         if (!fs.existsSync(kitRoot)) warnings.push(`${id}: installed kit copy missing at ${kitRoot}; skipping`);
-        else assets.push(...loadKitAssets(kitRoot, "local", warnings, errors));
+        else {
+          const loaded = loadKitAssets(kitRoot, "local", warnings, errors);
+          assets.push(...loaded.assets);
+          dependencies.push(...loaded.dependencies);
+          if (loaded.kit_id) presentKitIds.add(loaded.kit_id);
+        }
       });
     }
   }
+  // Activation-time cross-kit dependency enforcement: any declared dependency whose
+  // kit_id is not present among the union of built-in catalog kits and locally-installed
+  // kits is a hard error (feeds the errors[] -> activation-manifest -> non-zero exit path).
+  for (const dep of dependencies) {
+    if (!presentKitIds.has(dep.kit_id)) {
+      errors.push(`${dep.from_kit_id}: declares a dependency on kit '${dep.kit_id}'${dep.reason ? ` (${dep.reason})` : ""} which is not installed or activated. Install it with 'flow-agents kit install <source>' and re-activate, or remove the dependency declaration if it is no longer needed.`);
+    }
+  }
   return { assets, warnings, errors };
 }
 
@@ -134,7 +168,7 @@ const ACTIVATED_ASSET_CLASSES = new Set(["flows", "skills", "docs"]);
 
 export function activateCodexLocal(sourceRoot: string, dest: string): Record<string, unknown> {
   const inventory = readKitInventory(sourceRoot, dest);
-  const runtimeDir = path.join(dest, ".flow-agents", "runtime", "codex");
+  const runtimeDir = path.join(flowAgentsArtifactRoot(dest), "projections", "codex");
   const generated: Record<string, string>[] = [];
   const skipped: Record<string, string | null>[] = [];
   for (const asset of inventory.assets) {
@@ -152,7 +186,13 @@ export function activateCodexLocal(sourceRoot: string, dest: string): Record<str
       // agent's guidance index (AGENTS.md) can reference them and they are co-located
       // with flow definitions for the same kit.
       const filename = path.basename(asset.source_path);
-      const output = path.join(runtimeDir, asset.asset_class, safeSegment(asset.kit_id), filename);
+      // Namespace skills by BOTH kit id AND the skill's own directory name: every skill
+      // file is literally named SKILL.md, so keying only on kit id collides all of a
+      // kit's skills onto one .../<kit-id>/SKILL.md file. Docs keep the flat
+      // <kit-id>/<filename> layout (no per-directory collision found).
+      const output = asset.asset_class === "skills"
+        ? path.join(runtimeDir, asset.asset_class, safeSegment(asset.kit_id), safeSegment(path.basename(path.dirname(asset.source_path))), filename)
+        : path.join(runtimeDir, asset.asset_class, safeSegment(asset.kit_id), filename);
       fs.mkdirSync(path.dirname(output), { recursive: true });
       fs.copyFileSync(asset.source_path, output);
       generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id ?? "", source_path: asset.source_path.split(path.sep).join("/") });
@@ -177,11 +217,11 @@ export function activateCodexLocal(sourceRoot: string, dest: string): Record<str
 // layout knowledge. The Strands steering layer then reads the written runtime files.
 export function activateStrandsLocal(sourceRoot: string, dest: string): Record<string, unknown> {
   const inventory = readKitInventory(sourceRoot, dest);
-  // Runtime flows land at .flow-agents/runtime/strands/flows/<kit-id>/<asset-id>.flow.json
+  // Runtime flows land at .kontourai/flow-agents/projections/strands/flows/<kit-id>/<asset-id>.flow.json
   // so the Strands steering context can glob for *.flow.json under this path.
-  // Runtime skills land at .flow-agents/runtime/strands/skills/<kit-id>/<filename> and
-  // docs at .flow-agents/runtime/strands/docs/<kit-id>/<filename> for system-prompt injection.
-  const runtimeDir = path.join(dest, ".flow-agents", "runtime", "strands");
+  // Runtime skills land at .kontourai/flow-agents/projections/strands/skills/<kit-id>/<filename> and
+  // docs at .kontourai/flow-agents/projections/strands/docs/<kit-id>/<filename> for system-prompt injection.
+  const runtimeDir = path.join(flowAgentsArtifactRoot(dest), "projections", "strands");
   const generated: Record<string, string>[] = [];
   const skipped: Record<string, string | null>[] = [];
   for (const asset of inventory.assets) {
@@ -197,9 +237,15 @@ export function activateStrandsLocal(sourceRoot: string, dest: string): Record<s
     } else if (asset.asset_class === "skills" || asset.asset_class === "docs") {
       // Mirror the codex-local layout: strands/<class>/<kit-id>/<filename>.
       // The Strands system-prompt injection layer can glob for all *.md files under
-      // .flow-agents/runtime/strands/skills/ to include agent guidance in the context.
+      // .kontourai/flow-agents/projections/strands/skills/ to include agent guidance in the context.
       const filename = path.basename(asset.source_path);
-      const output = path.join(runtimeDir, asset.asset_class, safeSegment(asset.kit_id), filename);
+      // Namespace skills by BOTH kit id AND the skill's own directory name: every skill
+      // file is literally named SKILL.md, so keying only on kit id collides all of a
+      // kit's skills onto one .../<kit-id>/SKILL.md file. Docs keep the flat
+      // <kit-id>/<filename> layout (no per-directory collision found).
+      const output = asset.asset_class === "skills"
+        ? path.join(runtimeDir, asset.asset_class, safeSegment(asset.kit_id), safeSegment(path.basename(path.dirname(asset.source_path))), filename)
+        : path.join(runtimeDir, asset.asset_class, safeSegment(asset.kit_id), filename);
       fs.mkdirSync(path.dirname(output), { recursive: true });
       fs.copyFileSync(asset.source_path, output);
       generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id ?? "", source_path: asset.source_path.split(path.sep).join("/") });