@chrisdudek/yg 4.1.0 → 4.2.0

package/dist/bin.js

@@ -125,6 +125,7 @@ import { Command } from "commander";
 
 // src/cli/init.ts
 import chalk from "chalk";
+import { existsSync } from "fs";
 import { mkdir as mkdir2, writeFile as writeFile4, readdir as readdir2, readFile as readFile4, stat as stat2 } from "fs/promises";
 import path5 from "path";
 import { fileURLToPath } from "url";
@@ -191,7 +192,7 @@ The CLI (\`yg\`) reads and validates \u2014 it never modifies files. You create
 
 **Architecture** \u2014 \`yg-architecture.yaml\` defines the vocabulary: node types, default aspects per type, allowed parent types, allowed relation targets per type. This is the foundation \u2014 read it when starting work on a new repo. Changes require user confirmation. Structure details in \`schemas/yg-architecture.yaml\`.
 
-### How Aspects Reach a Node \u2014 7 Channels
+### How Aspects Reach a Node \u2014 7 Channels + Applicability Filter
 
 Aspects accumulate from multiple sources simultaneously. The reviewer checks ALL of them \u2014 the node must satisfy every aspect regardless of origin.
 
@@ -221,6 +222,36 @@ Consequences of this cascade:
 - Architecture default aspects apply to every node of that type automatically.
 - Implies chains expand recursively. Cycles are forbidden \u2014 CLI detects them.
 
+### Applicability Filter (\`when\`) \u2014 Evaluated on Every Channel
+
+Seven channels propagate aspects onto nodes. A separate mechanism \u2014 the \`when\`
+predicate \u2014 filters applicability. Every channel's attachment passes through
+\`when\` before the aspect becomes effective. The predicate is evaluated by the
+CLI against the graph (deterministic, no LLM call); if false, the aspect is
+silently skipped on that node.
+
+\`when\` can be declared globally on the aspect (applies across channels) or
+per attach site (per channel instance). Global and attach-site \`when\` combine
+via AND on each channel path. Multiple channels deliver independently \u2014 the
+aspect is effective if any channel's path passes both its global and
+attach-site filter.
+
+Use \`when\` when an aspect is meaningful for only a subset of nodes under a
+common attach channel. Example: \`external-api-error-mapping\` attached to
+type \`command\` but only applicable when the node calls \`service-client\` \u2014
+declare on the aspect:
+
+    when:
+      relations:
+        calls:
+          target_type: service-client
+
+Domain-neutral examples: a \`pii-encryption\` aspect attached to all
+repositories, but only applicable when the repository stores a field of
+type \`user-profile\`; an \`idempotency-key\` aspect required only for commands
+that emit events; a \`database-migration-review\` aspect only for nodes with
+\`has_mapping: true\` pointing at \`db/migrations/\`.
+
 ### Reviewer
 
 The reviewer is an LLM invoked by \`yg approve\`. It receives: the aspect's content.md + all source files of the node. It checks every rule from content.md against the code.
@@ -303,6 +334,13 @@ var DECISIONS = `## DECISIONS
 
 **Architecture change** \u2014 when existing types don't fit the project structure. Always confirm with the user. Never silently modify \`yg-architecture.yaml\`. If a relation between types is forbidden, present the constraint and let the user decide: use an allowed relation type, change the node type, or update the architecture.
 
+**\`when\` predicate on an aspect or attach site** \u2014 when the aspect applies to
+only a subset of nodes under a common attach channel. Prefer \`when\` over
+splitting node types (proliferation of types). Prefer \`when\` over leaving
+the decision to the reviewer textually inside \`content.md\`; \`when\` is
+deterministic, has zero LLM cost, and keeps the graph as the source of
+truth for applicability.
+
 ### Aspect Discovery
 
 Aspects emerge from patterns \u2014 greenfield and brownfield:
@@ -1133,10 +1171,23 @@ var MIGRATIONS = [
   }
 ];
 
+// src/formatters/message-builder.ts
+function buildIssueMessage(msg) {
+  return `${msg.what}
+${msg.why}
+${msg.next}`;
+}
+
 // src/cli/init.ts
 function getPackageRoot() {
-  const currentDir = path5.dirname(fileURLToPath(import.meta.url));
-  return path5.join(currentDir, "..");
+  let dir = path5.dirname(fileURLToPath(import.meta.url));
+  while (dir !== path5.dirname(dir)) {
+    if (existsSync(path5.join(dir, "package.json"))) {
+      return dir;
+    }
+    dir = path5.dirname(dir);
+  }
+  throw new Error("Could not locate package root (no package.json found walking up from init module).");
 }
 function getGraphSchemasDir() {
   return path5.join(getPackageRoot(), "graph-schemas");
@@ -1438,6 +1489,25 @@ async function createYggdrasilStructure(projectRoot, yggRoot, platform) {
   await writeFile4(path5.join(yggRoot, ".gitignore"), GITIGNORE_CONTENT, "utf-8");
   await installRulesForPlatform(projectRoot, platform);
 }
+async function runVersionUpgrade(projectRoot, yggRoot, fromVersion, toVersion, platform) {
+  const migrationResults = await runMigrations(fromVersion, MIGRATIONS, yggRoot);
+  await updateConfigVersion(yggRoot, toVersion);
+  await refreshSchemas(yggRoot);
+  const architecturePath = path5.join(yggRoot, "yg-architecture.yaml");
+  try {
+    await stat2(architecturePath);
+  } catch {
+    await writeFile4(architecturePath, DEFAULT_ARCHITECTURE, "utf-8");
+  }
+  const rulesPath = await installRulesForPlatform(projectRoot, platform);
+  const migrationActions = [];
+  const migrationWarnings = [];
+  for (const r of migrationResults) {
+    migrationActions.push(...r.actions);
+    migrationWarnings.push(...r.warnings);
+  }
+  return { rulesPath, migrationActions, migrationWarnings };
+}
 async function existingInit(projectRoot) {
   const yggRoot = path5.join(projectRoot, ".yggdrasil");
   if (!isTTY()) {
@@ -1448,33 +1518,28 @@ async function existingInit(projectRoot) {
   const currentVersion = await detectVersion(yggRoot);
   const cliVersion = await getCliVersion();
   if (currentVersion && currentVersion !== cliVersion) {
-    const migrate = await p.confirm({
-      message: `Graph version ${currentVersion} detected \u2014 CLI is ${cliVersion}. Run migration?`,
-      initialValue: true
-    });
-    assertNotCancelled(migrate);
-    if (migrate) {
-      const s = p.spinner();
-      s.start("Running migrations...");
-      const results = await runMigrations(currentVersion, MIGRATIONS, yggRoot);
-      await updateConfigVersion(yggRoot, cliVersion);
-      await refreshSchemas(yggRoot);
-      s.stop("Migration complete.");
-      for (const result of results) {
-        for (const action2 of result.actions) {
-          p.log.info(action2);
-        }
-        for (const warning of result.warnings) {
-          p.log.warning(warning);
-        }
-      }
-      p.log.step("Next steps:");
-      p.log.info("1. Run yg init again to configure reviewer (if not set)");
-      p.log.info("2. Run yg check to verify graph integrity");
-      p.log.info("3. Run yg approve on all nodes to establish baselines");
-      p.outro(chalk.green(`Migrated from ${currentVersion} to ${cliVersion}.`));
-      return;
-    }
+    p.log.step(`Graph version ${currentVersion} detected \u2014 CLI is ${cliVersion}. Upgrade required.`);
+    p.log.info("Select the agent platform so rules and schemas advance together.");
+    const platform = await promptPlatform();
+    const s = p.spinner();
+    s.start("Running migrations and installing rules...");
+    const result = await runVersionUpgrade(projectRoot, yggRoot, currentVersion, cliVersion, platform);
+    s.stop("Upgrade complete.");
+    for (const action2 of result.migrationActions) {
+      p.log.info(action2);
+    }
+    for (const warning of result.migrationWarnings) {
+      p.log.warning(warning);
+    }
+    p.log.step("Next steps:");
+    p.log.info("1. Run yg check to verify graph integrity");
+    p.log.info("2. Run yg approve on all nodes to establish baselines");
+    p.outro(
+      chalk.green(
+        `Migrated from ${currentVersion} to ${cliVersion}. Rules installed: ${path5.relative(projectRoot, result.rulesPath)}`
+      )
+    );
+    return;
   }
   const action = await p.select({
     message: "What would you like to do?",
@@ -1488,15 +1553,9 @@ async function existingInit(projectRoot) {
   switch (action) {
     case "upgrade": {
       const platform = await promptPlatform();
-      await refreshSchemas(yggRoot);
-      const architecturePath = path5.join(yggRoot, "yg-architecture.yaml");
-      try {
-        await stat2(architecturePath);
-      } catch {
-        await writeFile4(architecturePath, DEFAULT_ARCHITECTURE, "utf-8");
-      }
-      const rulesPath = await installRulesForPlatform(projectRoot, platform);
-      p.outro(chalk.green(`Rules and schemas refreshed: ${path5.relative(projectRoot, rulesPath)}`));
+      const fromVersion = currentVersion ?? cliVersion;
+      const result = await runVersionUpgrade(projectRoot, yggRoot, fromVersion, cliVersion, platform);
+      p.outro(chalk.green(`Rules and schemas refreshed: ${path5.relative(projectRoot, result.rulesPath)}`));
       break;
     }
     case "reviewer": {
@@ -1537,17 +1596,27 @@ function registerInitCommand(program2) {
           process.stderr.write(chalk.red("Error: No .yggdrasil/ directory found. Run 'yg init' first.\n"));
           process.exit(1);
         }
-        await refreshSchemas(yggRoot);
-        const architecturePath = path5.join(yggRoot, "yg-architecture.yaml");
-        try {
-          await stat2(architecturePath);
-        } catch {
-          await writeFile4(architecturePath, DEFAULT_ARCHITECTURE, "utf-8");
+        const toVersion = await getCliVersion();
+        const fromVersion = await detectVersion(yggRoot);
+        if (fromVersion === null) {
+          process.stderr.write(chalk.red(buildIssueMessage({
+            what: "No graph version detected.",
+            why: ".yggdrasil/yg-config.yaml is missing a 'version:' field, so --upgrade cannot determine which migrations to run.",
+            next: "Run 'yg init' interactively once to record the current version, then retry 'yg init --upgrade --platform <name>'."
+          }) + "\n"));
+          process.exit(1);
         }
-        await updateConfigVersion(yggRoot, await getCliVersion());
-        const rulesPath = await installRulesForPlatform(projectRoot, options.platform);
-        process.stdout.write(`Rules and schemas refreshed: ${path5.relative(projectRoot, rulesPath)}
-`);
+        const result = await runVersionUpgrade(
+          projectRoot,
+          yggRoot,
+          fromVersion,
+          toVersion,
+          options.platform
+        );
+        process.stdout.write(
+          `Rules and schemas refreshed: ${path5.relative(projectRoot, result.rulesPath)}
+`
+        );
         return;
       }
       let exists = false;
@@ -1704,7 +1773,219 @@ function normalizeProviderConfig(providerName, pc, generalConfig, filename) {
 // src/io/node-parser.ts
 import { readFile as readFile6 } from "fs/promises";
 import { parse as parseYaml4 } from "yaml";
-var RELATION_TYPES = [
+
+// src/io/when-parser.ts
+var RELATION_TYPES = /* @__PURE__ */ new Set([
+  "calls",
+  "uses",
+  "extends",
+  "implements",
+  "emits",
+  "listens"
+]);
+var ATOMIC_KEYS = /* @__PURE__ */ new Set(["relations", "descendants", "node"]);
+var BOOLEAN_KEYS = /* @__PURE__ */ new Set(["all_of", "any_of", "not"]);
+function parseWhen(raw, ctx) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`${ctx}: when must be a YAML mapping`);
+  }
+  const keys = Object.keys(raw);
+  if (keys.length === 0) {
+    throw new Error(`${ctx}: when mapping must not be empty`);
+  }
+  const booleanKeys = keys.filter((k) => BOOLEAN_KEYS.has(k));
+  const atomicKeys = keys.filter((k) => ATOMIC_KEYS.has(k));
+  const unknownKeys = keys.filter((k) => !BOOLEAN_KEYS.has(k) && !ATOMIC_KEYS.has(k));
+  if (unknownKeys.length > 0) {
+    throw new Error(`${ctx}: unknown when operator '${unknownKeys[0]}' (expected one of: all_of, any_of, not, relations, descendants, node)`);
+  }
+  if (booleanKeys.length > 0 && atomicKeys.length > 0) {
+    throw new Error(`${ctx}: when cannot mix boolean operators with atomic clauses at the same level`);
+  }
+  if (booleanKeys.length > 1) {
+    throw new Error(`${ctx}: when can have at most one boolean operator at a level (got: ${booleanKeys.join(", ")})`);
+  }
+  if (booleanKeys.length === 1) {
+    return parseBoolean(raw, booleanKeys[0], ctx);
+  }
+  return parseAtomic(raw, ctx);
+}
+function parseBoolean(raw, key, ctx) {
+  const val = raw[key];
+  if (key === "not") {
+    return { not: parseWhen(val, `${ctx}/not`) };
+  }
+  if (!Array.isArray(val)) {
+    throw new Error(`${ctx}: '${key}' must be an array`);
+  }
+  if (val.length === 0) {
+    throw new Error(`${ctx}: '${key}' array must not be empty`);
+  }
+  const items = val.map((v, i) => parseWhen(v, `${ctx}/${key}[${i}]`));
+  return key === "all_of" ? { all_of: items } : { any_of: items };
+}
+function parseAtomic(raw, ctx) {
+  const result = {};
+  if ("relations" in raw) {
+    result.relations = parseRelationClause(raw.relations, `${ctx}/relations`);
+  }
+  if ("descendants" in raw) {
+    result.descendants = parseDescendantsClause(raw.descendants, `${ctx}/descendants`);
+  }
+  if ("node" in raw) {
+    result.node = parseNodeClause(raw.node, `${ctx}/node`);
+  }
+  return result;
+}
+function parseRelationClause(raw, ctx) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`${ctx}: relations must be a YAML mapping keyed by relation type`);
+  }
+  const entries = Object.entries(raw);
+  if (entries.length === 0) {
+    throw new Error(`${ctx}: relations mapping must not be empty`);
+  }
+  const out = {};
+  for (const [relType, match] of entries) {
+    if (!RELATION_TYPES.has(relType)) {
+      throw new Error(`${ctx}: unknown relation type '${relType}' (valid: ${Array.from(RELATION_TYPES).join(", ")})`);
+    }
+    out[relType] = parseRelationMatch(match, `${ctx}/${relType}`);
+  }
+  return out;
+}
+function parseRelationMatch(raw, ctx) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`${ctx}: must be a YAML mapping`);
+  }
+  const obj = raw;
+  const allowed = /* @__PURE__ */ new Set(["target_type", "target", "consumes_port"]);
+  for (const k of Object.keys(obj)) {
+    if (!allowed.has(k)) {
+      throw new Error(`${ctx}: unknown field '${k}' (allowed: target_type, target, consumes_port)`);
+    }
+  }
+  const out = {};
+  if ("target_type" in obj) {
+    if (typeof obj.target_type !== "string" || obj.target_type.trim() === "") {
+      throw new Error(`${ctx}: target_type must be a non-empty string`);
+    }
+    out.target_type = obj.target_type.trim();
+  }
+  if ("target" in obj) {
+    if (typeof obj.target !== "string" || obj.target.trim() === "") {
+      throw new Error(`${ctx}: target must be a non-empty string (node path relative to model/)`);
+    }
+    out.target = obj.target.trim();
+  }
+  if ("consumes_port" in obj) {
+    if (typeof obj.consumes_port !== "string" || obj.consumes_port.trim() === "") {
+      throw new Error(`${ctx}: consumes_port must be a non-empty string`);
+    }
+    out.consumes_port = obj.consumes_port.trim();
+  }
+  if (Object.keys(out).length === 0) {
+    throw new Error(`${ctx}: at least one of target_type, target, consumes_port must be present`);
+  }
+  return out;
+}
+function parseDescendantsClause(raw, ctx) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`${ctx}: descendants must be a YAML mapping`);
+  }
+  const obj = raw;
+  const allowed = /* @__PURE__ */ new Set(["relations", "type", "has_port"]);
+  for (const k of Object.keys(obj)) {
+    if (!allowed.has(k)) {
+      throw new Error(`${ctx}: unknown field '${k}' (allowed: relations, type, has_port)`);
+    }
+  }
+  const out = {};
+  if ("relations" in obj) {
+    out.relations = parseRelationClause(obj.relations, `${ctx}/relations`);
+  }
+  if ("type" in obj) {
+    if (typeof obj.type !== "string" || obj.type.trim() === "") {
+      throw new Error(`${ctx}: type must be a non-empty string`);
+    }
+    out.type = obj.type.trim();
+  }
+  if ("has_port" in obj) {
+    if (typeof obj.has_port !== "string" || obj.has_port.trim() === "") {
+      throw new Error(`${ctx}: has_port must be a non-empty string`);
+    }
+    out.has_port = obj.has_port.trim();
+  }
+  if (Object.keys(out).length === 0) {
+    throw new Error(`${ctx}: at least one of relations, type, has_port must be present`);
+  }
+  return out;
+}
+function parseNodeClause(raw, ctx) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`${ctx}: node must be a YAML mapping`);
+  }
+  const obj = raw;
+  const allowed = /* @__PURE__ */ new Set(["type", "has_port", "has_mapping"]);
+  for (const k of Object.keys(obj)) {
+    if (!allowed.has(k)) {
+      throw new Error(`${ctx}: unknown field '${k}' (allowed: type, has_port, has_mapping)`);
+    }
+  }
+  const out = {};
+  if ("type" in obj) {
+    if (typeof obj.type !== "string" || obj.type.trim() === "") {
+      throw new Error(`${ctx}: type must be a non-empty string`);
+    }
+    out.type = obj.type.trim();
+  }
+  if ("has_port" in obj) {
+    if (typeof obj.has_port !== "string" || obj.has_port.trim() === "") {
+      throw new Error(`${ctx}: has_port must be a non-empty string`);
+    }
+    out.has_port = obj.has_port.trim();
+  }
+  if ("has_mapping" in obj) {
+    if (typeof obj.has_mapping !== "boolean") {
+      throw new Error(`${ctx}: has_mapping must be a boolean`);
+    }
+    out.has_mapping = obj.has_mapping;
+  }
+  if (Object.keys(out).length === 0) {
+    throw new Error(`${ctx}: at least one of type, has_port, has_mapping must be present`);
+  }
+  return out;
+}
+function parseAspectAttachment(raw, ctx) {
+  if (typeof raw === "string") {
+    const id = raw.trim();
+    if (id === "") {
+      throw new Error(`${ctx}: aspect id must be a non-empty string`);
+    }
+    return { id };
+  }
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+    const obj = raw;
+    if (typeof obj.id !== "string" || obj.id.trim() === "") {
+      throw new Error(`${ctx}: object form requires 'id' as a non-empty string`);
+    }
+    const result = { id: obj.id.trim() };
+    const allowed = /* @__PURE__ */ new Set(["id", "when"]);
+    for (const k of Object.keys(obj)) {
+      if (!allowed.has(k)) {
+        throw new Error(`${ctx}: unknown field '${k}' in aspect attachment (allowed: id, when)`);
+      }
+    }
+    if ("when" in obj) {
+      result.when = parseWhen(obj.when, `${ctx}/when`);
+    }
+    return result;
+  }
+  throw new Error(`${ctx}: aspect attachment must be a string or an object with 'id' (and optional 'when')`);
+}
+
+// src/io/node-parser.ts
+var RELATION_TYPES2 = [
   "uses",
   "calls",
   "extends",
@@ -1713,7 +1994,7 @@ var RELATION_TYPES = [
   "listens"
 ];
 function isValidRelationType(t) {
-  return typeof t === "string" && RELATION_TYPES.includes(t);
+  return typeof t === "string" && RELATION_TYPES2.includes(t);
 }
 async function parseNodeYaml(filePath) {
   const content = await readFile6(filePath, "utf-8");
@@ -1730,52 +2011,43 @@ async function parseNodeYaml(filePath) {
   const description = typeof raw.description === "string" ? raw.description.trim() : void 0;
   const relations = parseRelations(raw.relations, filePath);
   const mapping = parseMapping(raw.mapping, filePath);
-  const aspects = parseAspects(raw.aspects, filePath);
+  const aspectsResult = parseAspects(raw.aspects, filePath);
   const ports = parsePorts(raw.ports, filePath);
   return {
     name: raw.name.trim(),
     type: raw.type.trim(),
     description,
-    aspects,
+    aspects: aspectsResult.aspects,
+    ...aspectsResult.aspectWhens && { aspectWhens: aspectsResult.aspectWhens },
     relations: relations.length > 0 ? relations : void 0,
     mapping,
     ports
   };
 }
 function parseAspects(raw, filePath) {
-  if (raw === void 0 || raw === null) return void 0;
+  if (raw === void 0 || raw === null) return {};
   if (!Array.isArray(raw)) {
     throw new Error(`yg-node.yaml at ${filePath}: 'aspects' must be an array`);
   }
-  if (raw.length === 0) return void 0;
-  const result = [];
-  const seenAspects = /* @__PURE__ */ new Set();
+  if (raw.length === 0) return {};
+  const aspects = [];
+  let aspectWhens;
+  const seen = /* @__PURE__ */ new Set();
   for (let i = 0; i < raw.length; i++) {
-    const item = raw[i];
-    let aspectId;
-    if (typeof item === "string") {
-      aspectId = item.trim();
-      if (aspectId === "") {
-        throw new Error(
-          `yg-node.yaml at ${filePath}: aspects[${i}] must be a non-empty string`
-        );
-      }
-    } else if (typeof item === "object" && item !== null) {
-      throw new Error(
-        `yg-node.yaml at ${filePath}: aspects must be an array of strings.`
-      );
-    } else {
-      throw new Error(`yg-node.yaml at ${filePath}: aspects[${i}] must be a string`);
+    const parsed = parseAspectAttachment(
+      raw[i],
+      `yg-node.yaml at ${filePath}: aspects[${i}]`
+    );
+    if (seen.has(parsed.id)) {
+      throw new Error(`yg-node.yaml at ${filePath}: duplicate aspect '${parsed.id}' in aspects list`);
     }
-    if (seenAspects.has(aspectId)) {
-      throw new Error(
-        `yg-node.yaml at ${filePath}: duplicate aspect '${aspectId}' in aspects list`
-      );
+    seen.add(parsed.id);
+    aspects.push(parsed.id);
+    if (parsed.when) {
+      (aspectWhens ??= {})[parsed.id] = parsed.when;
     }
-    seenAspects.add(aspectId);
-    result.push(aspectId);
   }
-  return result.length > 0 ? result : void 0;
+  return { aspects: aspects.length > 0 ? aspects : void 0, aspectWhens };
 }
 function parseRelations(raw, filePath) {
   if (raw === void 0) return [];
@@ -1867,13 +2139,28 @@ function parsePorts(rawPorts, filePath) {
     if (!Array.isArray(obj.aspects)) {
       throw new Error(`yg-node.yaml at ${filePath}: ports.${name}.aspects must be an array`);
     }
-    const aspects = obj.aspects.map((a, i) => {
-      if (typeof a !== "string" || a.trim() === "") {
-        throw new Error(`yg-node.yaml at ${filePath}: ports.${name}.aspects[${i}] must be a non-empty string`);
+    const portAspects = [];
+    let portAspectWhens;
+    const seenPortAspects = /* @__PURE__ */ new Set();
+    for (let i = 0; i < obj.aspects.length; i++) {
+      const parsed = parseAspectAttachment(
+        obj.aspects[i],
+        `yg-node.yaml at ${filePath}: ports.${name}.aspects[${i}]`
+      );
+      if (seenPortAspects.has(parsed.id)) {
+        throw new Error(`yg-node.yaml at ${filePath}: ports.${name}.aspects has duplicate '${parsed.id}'`);
       }
-      return a.trim();
-    });
-    ports[name] = { description: obj.description.trim(), aspects };
+      seenPortAspects.add(parsed.id);
+      portAspects.push(parsed.id);
+      if (parsed.when) {
+        (portAspectWhens ??= {})[parsed.id] = parsed.when;
+      }
+    }
+    ports[name] = {
+      description: obj.description.trim(),
+      aspects: portAspects,
+      ...portAspectWhens && { aspectWhens: portAspectWhens }
+    };
   }
   return Object.keys(ports).length > 0 ? ports : void 0;
 }
@@ -1924,17 +2211,34 @@ async function parseAspect(aspectDir, aspectYamlPath, id) {
   const description = typeof raw.description === "string" ? raw.description.trim() : void 0;
   const artifacts = await readArtifacts(aspectDir, ["yg-aspect.yaml"]);
   let implies;
+  let impliesWhens;
   if (raw.implies !== void 0) {
     if (!Array.isArray(raw.implies)) {
-      throw new Error(`yg-aspect.yaml at ${aspectYamlPath}: 'implies' must be an array of strings`);
+      throw new Error(`yg-aspect.yaml at ${aspectYamlPath}: 'implies' must be an array`);
+    }
+    implies = [];
+    for (let i = 0; i < raw.implies.length; i++) {
+      const parsed = parseAspectAttachment(
+        raw.implies[i],
+        `yg-aspect.yaml at ${aspectYamlPath}: implies[${i}]`
+      );
+      implies.push(parsed.id);
+      if (parsed.when) {
+        (impliesWhens ??= {})[parsed.id] = parsed.when;
+      }
     }
-    implies = raw.implies.filter((t) => typeof t === "string");
+  }
+  let when;
+  if (raw.when !== void 0) {
+    when = parseWhen(raw.when, `yg-aspect.yaml at ${aspectYamlPath}: when`);
   }
   return {
     name: raw.name.trim(),
     id: idTrimmed,
     description,
     implies,
+    ...impliesWhens && { impliesWhens },
+    ...when && { when },
     artifacts
   };
 }
@@ -1966,19 +2270,30 @@ async function parseFlow(flowDir, flowYamlPath) {
     );
   }
   let aspects;
+  let aspectWhens;
   if (raw.aspects !== void 0) {
     if (!Array.isArray(raw.aspects)) {
       throw new Error(`yg-flow.yaml at ${flowYamlPath}: 'aspects' must be an array of strings`);
     }
-    const aspectTags = raw.aspects.filter((a) => typeof a === "string");
-    aspects = aspectTags.length > 0 ? aspectTags : [];
+    aspects = [];
+    for (let i = 0; i < raw.aspects.length; i++) {
+      const parsed = parseAspectAttachment(
+        raw.aspects[i],
+        `yg-flow.yaml at ${flowYamlPath}: aspects[${i}]`
+      );
+      aspects.push(parsed.id);
+      if (parsed.when) {
+        (aspectWhens ??= {})[parsed.id] = parsed.when;
+      }
+    }
   }
   return {
     path: path8.basename(flowDir),
     name: raw.name.trim(),
     description,
     nodes: nodePaths,
-    ...aspects !== void 0 && { aspects }
+    ...aspects !== void 0 && { aspects },
+    ...aspectWhens && { aspectWhens }
   };
 }
 
@@ -2025,12 +2340,28 @@ async function parseArchitecture(filePath) {
         `yg-architecture.yaml: node type '${typeName}' has unknown field 'integration_aspects'. Use ports on the target node instead.`
       );
     }
-    const aspects = Array.isArray(entry.aspects) ? entry.aspects.filter((t) => typeof t === "string") : void 0;
+    let aspects;
+    let aspectWhens;
+    if (Array.isArray(entry.aspects)) {
+      aspects = [];
+      for (let i = 0; i < entry.aspects.length; i++) {
+        const parsed = parseAspectAttachment(
+          entry.aspects[i],
+          `yg-architecture.yaml: node_types.${typeName}.aspects[${i}]`
+        );
+        aspects.push(parsed.id);
+        if (parsed.when) {
+          (aspectWhens ??= {})[parsed.id] = parsed.when;
+        }
+      }
+      if (aspects.length === 0) aspects = void 0;
+    }
     const parents = Array.isArray(entry.parents) ? entry.parents.filter((t) => typeof t === "string") : void 0;
     const relations = parseRelations2(entry.relations, typeName);
     nodeTypes[typeName] = {
       description: entry.description,
-      aspects: aspects && aspects.length > 0 ? aspects : void 0,
+      aspects,
+      ...aspectWhens && { aspectWhens },
       parents: parents && parents.length > 0 ? parents : void 0,
       relations
     };
@@ -2307,57 +2638,191 @@ async function loadSchemas(schemasDir) {
 import { readFile as readFile13 } from "fs/promises";
 import path12 from "path";
 
+// src/core/when-evaluator.ts
+function evaluateWhen(predicate, node, graph) {
+  if ("all_of" in predicate) {
+    return predicate.all_of.every((p2) => evaluateWhen(p2, node, graph));
+  }
+  if ("any_of" in predicate) {
+    return predicate.any_of.some((p2) => evaluateWhen(p2, node, graph));
+  }
+  if ("not" in predicate) {
+    return !evaluateWhen(predicate.not, node, graph);
+  }
+  return evaluateAtomic(predicate, node, graph);
+}
+function evaluateAtomic(clause, node, graph) {
+  if (clause.relations) {
+    if (!evaluateRelationClause(clause.relations, node.meta.relations ?? [], graph)) return false;
+  }
+  if (clause.descendants) {
+    if (!evaluateDescendantsClause(clause.descendants, node, graph)) return false;
+  }
+  if (clause.node) {
+    if (!evaluateNodeClause(clause.node, node)) return false;
+  }
+  return true;
+}
+function evaluateRelationClause(rc, relations, graph) {
+  for (const [relType, match] of Object.entries(rc)) {
+    if (!match) continue;
+    const candidates = relations.filter((r) => r.type === relType);
+    if (!candidates.some((r) => matchesRelation(r, match, graph))) {
+      return false;
+    }
+  }
+  return true;
+}
+function matchesRelation(r, match, graph) {
+  if (match.target !== void 0 && r.target !== match.target) return false;
+  if (match.target_type !== void 0) {
+    const tgt = graph.nodes.get(r.target);
+    if (!tgt || tgt.meta.type !== match.target_type) return false;
+  }
+  if (match.consumes_port !== void 0) {
+    if (!r.consumes || !r.consumes.includes(match.consumes_port)) return false;
+  }
+  return true;
+}
+function evaluateDescendantsClause(dc, node, graph) {
+  const descendants = collectDescendants(node);
+  if (descendants.length === 0) return false;
+  if (dc.type !== void 0) {
+    if (!descendants.some((d) => d.meta.type === dc.type)) return false;
+  }
+  if (dc.has_port !== void 0) {
+    if (!descendants.some((d) => d.meta.ports && Object.prototype.hasOwnProperty.call(d.meta.ports, dc.has_port))) {
+      return false;
+    }
+  }
+  if (dc.relations) {
+    if (!descendants.some((d) => evaluateRelationClause(dc.relations, d.meta.relations ?? [], graph))) {
+      return false;
+    }
+  }
+  return true;
+}
+function evaluateNodeClause(nc, node) {
+  if (nc.type !== void 0 && node.meta.type !== nc.type) return false;
+  if (nc.has_port !== void 0) {
+    if (!node.meta.ports || !Object.prototype.hasOwnProperty.call(node.meta.ports, nc.has_port)) return false;
+  }
+  if (nc.has_mapping !== void 0) {
+    const has = (node.meta.mapping?.length ?? 0) > 0;
+    if (has !== nc.has_mapping) return false;
+  }
+  return true;
+}
+function collectDescendants(node) {
+  const out = [];
+  const queue = [...node.children];
+  while (queue.length > 0) {
+    const curr = queue.shift();
+    out.push(curr);
+    for (const c of curr.children) queue.push(c);
+  }
+  return out;
+}
+
 // src/core/effective-aspects.ts
 function computeEffectiveAspects(node, graph) {
-  const raw = /* @__PURE__ */ new Set();
+  const direct = /* @__PURE__ */ new Set();
+  const ancestors = collectAncestors(node);
+  const tryAdd = (aspectId, attachWhen) => {
+    const aspectDef = graph.aspects.find((a) => a.id === aspectId);
+    const globalWhen = aspectDef?.when;
+    if (globalWhen && !evaluateWhen(globalWhen, node, graph)) {
+      debugWrite(`[effective-aspects] node '${node.path}' aspect '${aspectId}' filtered: global when=false`);
+      return;
+    }
+    if (attachWhen && !evaluateWhen(attachWhen, node, graph)) {
+      debugWrite(`[effective-aspects] node '${node.path}' aspect '${aspectId}' filtered: attach-site when=false`);
+      return;
+    }
+    direct.add(aspectId);
+  };
   for (const id of node.meta.aspects ?? []) {
-    raw.add(id);
+    tryAdd(id, node.meta.aspectWhens?.[id]);
   }
-  const ancestors = collectAncestors(node);
   for (const ancestor of ancestors) {
     for (const id of ancestor.meta.aspects ?? []) {
-      raw.add(id);
+      tryAdd(id, ancestor.meta.aspectWhens?.[id]);
     }
   }
   if (graph.architecture) {
     const typeDef = graph.architecture.node_types[node.meta.type];
     for (const id of typeDef?.aspects ?? []) {
-      raw.add(id);
+      tryAdd(id, typeDef?.aspectWhens?.[id]);
     }
   }
   if (graph.architecture) {
     for (const ancestor of ancestors) {
       const typeDef = graph.architecture.node_types[ancestor.meta.type];
       for (const id of typeDef?.aspects ?? []) {
-        raw.add(id);
+        tryAdd(id, typeDef?.aspectWhens?.[id]);
       }
     }
   }
   const allPaths = /* @__PURE__ */ new Set([node.path, ...ancestors.map((a) => a.path)]);
   for (const flow of graph.flows) {
-    if (flow.nodes.some((n) => allPaths.has(n))) {
-      for (const id of flow.aspects ?? []) {
-        raw.add(id);
-      }
+    if (!flow.nodes.some((n) => allPaths.has(n))) continue;
+    for (const id of flow.aspects ?? []) {
+      tryAdd(id, flow.aspectWhens?.[id]);
     }
   }
   if (node.meta.relations) {
     for (const relation of node.meta.relations) {
       const targetNode = graph.nodes.get(relation.target);
       if (!targetNode) continue;
-      if (relation.consumes && targetNode.meta.ports) {
-        for (const portName of relation.consumes) {
-          const port = targetNode.meta.ports[portName];
-          if (port?.aspects) {
-            for (const id of port.aspects) {
-              raw.add(id);
-            }
-          }
+      if (!relation.consumes || !targetNode.meta.ports) continue;
+      for (const portName of relation.consumes) {
+        const port = targetNode.meta.ports[portName];
+        if (!port?.aspects) continue;
+        for (const id of port.aspects) {
+          tryAdd(id, port.aspectWhens?.[id]);
         }
       }
     }
   }
-  return expandImplies(raw, graph);
+  return expandImpliesFiltered(direct, node, graph);
+}
+function expandImpliesFiltered(directIds, node, graph) {
+  const idToAspect = /* @__PURE__ */ new Map();
+  for (const a of graph.aspects) idToAspect.set(a.id, a);
+  const result = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const stack = /* @__PURE__ */ new Set();
+  const visit = (id, implierId) => {
+    if (stack.has(id)) {
+      throw new Error(`Aspect implies cycle detected involving aspect '${id}'`);
+    }
+    if (visited.has(id)) return;
+    const aspectDef = idToAspect.get(id);
+    if (aspectDef?.when && !evaluateWhen(aspectDef.when, node, graph)) {
+      debugWrite(`[effective-aspects] node '${node.path}' aspect '${id}' filtered: global when=false (implies path)`);
+      return;
+    }
+    if (implierId) {
+      const implierDef = idToAspect.get(implierId);
+      const perImplies = implierDef?.impliesWhens?.[id];
+      if (perImplies && !evaluateWhen(perImplies, node, graph)) {
+        debugWrite(`[effective-aspects] node '${node.path}' aspect '${id}' filtered: impliesWhens from '${implierId}' is false`);
+        return;
+      }
+    }
+    stack.add(id);
+    visited.add(id);
+    result.add(id);
+    const implies = aspectDef?.implies;
+    if (implies) {
+      for (const implied of implies) {
+        visit(implied, id);
+      }
+    }
+    stack.delete(id);
+  };
+  for (const id of directIds) visit(id, null);
+  return result;
 }
 function getAspectSource(aspectId, node, graph) {
   if (node.meta.aspects?.includes(aspectId)) {
@@ -2424,37 +2889,6 @@ function collectAncestors(node) {
   }
   return ancestors;
 }
-function expandImplies(aspectIds, graph) {
-  const idToImplies = /* @__PURE__ */ new Map();
-  for (const aspect of graph.aspects) {
-    if (aspect.implies) {
-      idToImplies.set(aspect.id, aspect.implies);
-    }
-  }
-  const result = /* @__PURE__ */ new Set();
-  const visited = /* @__PURE__ */ new Set();
-  const stack = /* @__PURE__ */ new Set();
-  function collect(id) {
-    if (stack.has(id)) {
-      throw new Error(`Aspect implies cycle detected involving aspect '${id}'`);
-    }
-    if (visited.has(id)) return;
-    stack.add(id);
-    visited.add(id);
-    result.add(id);
-    const implies = idToImplies.get(id);
-    if (implies) {
-      for (const implied of implies) {
-        collect(implied);
-      }
-    }
-    stack.delete(id);
-  }
-  for (const id of aspectIds) {
-    collect(id);
-  }
-  return result;
-}
 
 // src/core/context-builder.ts
 var STRUCTURAL_RELATION_TYPES = /* @__PURE__ */ new Set(["uses", "calls", "extends", "implements"]);
@@ -2847,13 +3281,6 @@ async function expandMappingPaths(projectRoot, mappingPaths) {
   return result;
 }
 
-// src/formatters/message-builder.ts
-function buildIssueMessage(msg) {
-  return `${msg.what}
-${msg.why}
-${msg.next}`;
-}
-
 // src/core/validator.ts
 async function validate(graph, scope = "all") {
   const issues = [];
@@ -2904,6 +3331,7 @@ async function validate(graph, scope = "all") {
   issues.push(...checkPortAspectsDefined(graph));
   issues.push(...checkPortConsumes(graph));
   issues.push(...checkOrphanedAspects(graph));
+  issues.push(...checkWhenReferences(graph));
   let filtered = issues;
   let nodesScanned = graph.nodes.size;
   const normalizedScope = scope.trim().replace(/\\/g, "/").replace(/\/+$/, "");
@@ -3721,6 +4149,141 @@ function checkOrphanedAspects(graph) {
   }
   return issues;
 }
+function checkWhenReferences(graph) {
+  const issues = [];
+  const knownTypes = new Set(Object.keys(graph.architecture?.node_types ?? {}));
+  const visitPredicate = (p2, ctx) => {
+    if ("all_of" in p2) {
+      p2.all_of.forEach((c, i) => visitPredicate(c, `${ctx}/all_of[${i}]`));
+      return;
+    }
+    if ("any_of" in p2) {
+      p2.any_of.forEach((c, i) => visitPredicate(c, `${ctx}/any_of[${i}]`));
+      return;
+    }
+    if ("not" in p2) {
+      visitPredicate(p2.not, `${ctx}/not`);
+      return;
+    }
+    visitAtomic(p2, ctx);
+  };
+  const visitAtomic = (a, ctx) => {
+    if (a.relations) visitRelationClause(a.relations, `${ctx}/relations`);
+    if (a.descendants) visitDescendantsClause(a.descendants, `${ctx}/descendants`);
+    if (a.node) visitNodeClause(a.node, `${ctx}/node`);
+  };
+  const visitRelationClause = (rc, ctx) => {
+    for (const [relType, match] of Object.entries(rc)) {
+      if (!match) continue;
+      if (match.target_type !== void 0 && !knownTypes.has(match.target_type)) {
+        issues.push({
+          severity: "error",
+          code: "when-unknown-type",
+          rule: "when-unknown-type",
+          message: buildIssueMessage({
+            what: `Unknown node type '${match.target_type}' in when at ${ctx}/${relType}.target_type.`,
+            why: "The predicate references a type that is not defined in yg-architecture.yaml; it will never evaluate.",
+            next: `Fix the type name or define it in yg-architecture.yaml. Known types: ${Array.from(knownTypes).join(", ")}.`
+          })
+        });
+      }
+      if (match.target !== void 0 && !graph.nodes.has(match.target)) {
+        issues.push({
+          severity: "error",
+          code: "when-unknown-node",
+          rule: "when-unknown-node",
+          message: buildIssueMessage({
+            what: `Referenced node '${match.target}' in when at ${ctx}/${relType}.target does not exist.`,
+            why: "The predicate targets a node that is not in the graph.",
+            next: `Fix the node path or add the node under .yggdrasil/model/.`
+          })
+        });
+      }
+      if (match.consumes_port !== void 0 && match.target !== void 0) {
+        const tgt = graph.nodes.get(match.target);
+        if (tgt && !(tgt.meta.ports && match.consumes_port in tgt.meta.ports)) {
+          issues.push({
+            severity: "error",
+            code: "when-unknown-port",
+            rule: "when-unknown-port",
+            message: buildIssueMessage({
+              what: `Port '${match.consumes_port}' is not declared on node '${match.target}' in when at ${ctx}/${relType}.consumes_port.`,
+              why: "The predicate references a port that does not exist on the target node.",
+              next: `Fix the port name or add it to .yggdrasil/model/${match.target}/yg-node.yaml.`
+            })
+          });
+        }
+      }
+    }
+  };
+  const visitDescendantsClause = (dc, ctx) => {
+    if (dc.relations) visitRelationClause(dc.relations, `${ctx}/relations`);
+    if (dc.type !== void 0 && !knownTypes.has(dc.type)) {
+      issues.push({
+        severity: "error",
+        code: "when-unknown-type",
+        rule: "when-unknown-type",
+        message: buildIssueMessage({
+          what: `Unknown node type '${dc.type}' in when at ${ctx}/type.`,
+          why: "The predicate references a type that is not defined in yg-architecture.yaml.",
+          next: `Fix the type name or define it in yg-architecture.yaml. Known types: ${Array.from(knownTypes).join(", ")}.`
+        })
+      });
+    }
+  };
+  const visitNodeClause = (nc, ctx) => {
+    if (nc.type !== void 0 && !knownTypes.has(nc.type)) {
+      issues.push({
+        severity: "error",
+        code: "when-unknown-type",
+        rule: "when-unknown-type",
+        message: buildIssueMessage({
+          what: `Unknown node type '${nc.type}' in when at ${ctx}/type.`,
+          why: "The predicate references a type that is not defined in yg-architecture.yaml.",
+          next: `Fix the type name or define it in yg-architecture.yaml. Known types: ${Array.from(knownTypes).join(", ")}.`
+        })
+      });
+    }
+  };
+  for (const aspect of graph.aspects) {
+    if (aspect.when) visitPredicate(aspect.when, `aspect '${aspect.id}' when`);
+    if (aspect.impliesWhens) {
+      for (const [targetId, pred] of Object.entries(aspect.impliesWhens)) {
+        visitPredicate(pred, `aspect '${aspect.id}' implies[${targetId}] when`);
+      }
+    }
+  }
+  if (graph.architecture) {
+    for (const [typeName, typeDef] of Object.entries(graph.architecture.node_types)) {
+      if (!typeDef.aspectWhens) continue;
+      for (const [aspectId, pred] of Object.entries(typeDef.aspectWhens)) {
+        visitPredicate(pred, `architecture node_types.${typeName} aspectWhens[${aspectId}]`);
+      }
+    }
+  }
+  for (const [nodePath, node] of graph.nodes) {
+    if (node.meta.aspectWhens) {
+      for (const [aspectId, pred] of Object.entries(node.meta.aspectWhens)) {
+        visitPredicate(pred, `node '${nodePath}' aspectWhens[${aspectId}]`);
+      }
+    }
+    if (node.meta.ports) {
+      for (const [portName, portDef] of Object.entries(node.meta.ports)) {
+        if (!portDef.aspectWhens) continue;
+        for (const [aspectId, pred] of Object.entries(portDef.aspectWhens)) {
+          visitPredicate(pred, `node '${nodePath}' ports.${portName} aspectWhens[${aspectId}]`);
+        }
+      }
+    }
+  }
+  for (const flow of graph.flows) {
+    if (!flow.aspectWhens) continue;
+    for (const [aspectId, pred] of Object.entries(flow.aspectWhens)) {
+      visitPredicate(pred, `flow '${flow.path}' aspectWhens[${aspectId}]`);
+    }
+  }
+  return issues;
+}
 
 // src/cli/owner.ts
 import path15 from "path";
@@ -4018,12 +4581,14 @@ async function writeNodeDriftState(yggRoot, nodePath, nodeState) {
   const content = JSON.stringify(nodeState, null, 2) + "\n";
   await writeFile5(filePath, content, "utf-8");
 }
-async function garbageCollectDriftState(yggRoot, validNodePaths) {
+async function garbageCollectDriftState(yggRoot, validNodePaths, shouldKeep) {
   const driftDir = path16.join(yggRoot, DRIFT_STATE_DIR);
   const allNodePaths = await scanJsonFiles(driftDir, driftDir);
   const removed = [];
   for (const nodePath of allNodePaths) {
-    if (!validNodePaths.has(nodePath)) {
+    const inGraph = validNodePaths.has(nodePath);
+    const keep = inGraph && (shouldKeep ? shouldKeep(nodePath) : true);
+    if (!keep) {
       const filePath = nodeStatePath(yggRoot, nodePath);
       await rm2(filePath);
       await removeEmptyParents(filePath, driftDir);
@@ -4302,7 +4867,16 @@ function getChildMappingExclusions(graph, nodePath) {
 }
 async function runGC(graph) {
   const validPaths = new Set(graph.nodes.keys());
-  return garbageCollectDriftState(graph.rootPath, validPaths);
+  return garbageCollectDriftState(
+    graph.rootPath,
+    validPaths,
+    (nodePath) => {
+      const node = graph.nodes.get(nodePath);
+      if (!node) return false;
+      const effective = computeEffectiveAspects(node, graph);
+      return effective.size > 0;
+    }
+  );
 }
 async function commitApproval(yggRoot, result) {
   if (result.pendingDriftState) {
@@ -4602,6 +5176,15 @@ async function runCheck(graph, gitTrackedFiles) {
     coverageIssue = buildCoverageIssue(uncovered, totalFiles);
   }
   const orphanedPaths = await detectOrphanedDriftState(graph);
+  await garbageCollectDriftState(
+    graph.rootPath,
+    new Set(graph.nodes.keys()),
+    (nodePath) => {
+      const node = graph.nodes.get(nodePath);
+      if (!node) return false;
+      return computeEffectiveAspects(node, graph).size > 0;
+    }
+  );
   const yggRelative = path19.relative(path19.dirname(graph.rootPath), graph.rootPath).replace(/\\/g, "/").replace(/\/+$/, "");
   const orphanWarnings = orphanedPaths.map((p2) => ({
     severity: "warning",
@@ -5250,26 +5833,57 @@ async function loadSecrets(rootPath, providerName) {
     return void 0;
   }
   const raw = parseYaml9(content);
-  if (!raw) return void 0;
-  if (raw.reviewer && typeof raw.reviewer === "object") {
-    const reviewerRaw = raw.reviewer;
-    if (!providerName) return void 0;
-    const providerKey = providerName;
-    const providerSection = reviewerRaw[providerKey];
-    if (!providerSection || typeof providerSection !== "object") return void 0;
-    return extractSecretFields(providerSection);
-  }
-  return void 0;
-}
-function extractSecretFields(raw) {
+  if (raw === null || raw === void 0) return void 0;
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`yg-secrets.yaml: top level must be a YAML mapping`);
+  }
+  const rawObj = raw;
+  if (rawObj.reviewer === void 0) return void 0;
+  if (typeof rawObj.reviewer !== "object" || rawObj.reviewer === null || Array.isArray(rawObj.reviewer)) {
+    throw new Error(`yg-secrets.yaml: 'reviewer' must be a YAML mapping`);
+  }
+  if (!providerName) return void 0;
+  const reviewerRaw = rawObj.reviewer;
+  const providerSection = reviewerRaw[providerName];
+  if (providerSection === void 0) return void 0;
+  if (typeof providerSection !== "object" || providerSection === null || Array.isArray(providerSection)) {
+    throw new Error(`yg-secrets.yaml: 'reviewer.${providerName}' must be a YAML mapping`);
+  }
+  return extractSecretFields(providerSection, providerName);
+}
+function extractSecretFields(raw, providerName) {
+  const ctx = (field) => `yg-secrets.yaml at reviewer.${providerName}.${field}`;
   const partial = {};
-  if (typeof raw.api_key === "string") partial.api_key = raw.api_key;
-  if (typeof raw.provider === "string") partial.provider = raw.provider;
-  if (typeof raw.model === "string") partial.model = raw.model;
-  if (typeof raw.endpoint === "string") partial.endpoint = raw.endpoint;
-  if (typeof raw.temperature === "number") partial.temperature = raw.temperature;
-  if (typeof raw.consensus === "number") partial.consensus = raw.consensus;
-  if (raw.max_tokens !== void 0) partial.max_tokens = raw.max_tokens;
+  if (raw.api_key !== void 0) {
+    if (typeof raw.api_key !== "string") throw new Error(`${ctx("api_key")}: must be a string`);
+    partial.api_key = raw.api_key;
+  }
+  if (raw.provider !== void 0) {
+    if (typeof raw.provider !== "string") throw new Error(`${ctx("provider")}: must be a string`);
+    partial.provider = raw.provider;
+  }
+  if (raw.model !== void 0) {
+    if (typeof raw.model !== "string") throw new Error(`${ctx("model")}: must be a string`);
+    partial.model = raw.model;
+  }
+  if (raw.endpoint !== void 0) {
+    if (typeof raw.endpoint !== "string") throw new Error(`${ctx("endpoint")}: must be a string`);
+    partial.endpoint = raw.endpoint;
+  }
+  if (raw.temperature !== void 0) {
+    if (typeof raw.temperature !== "number") throw new Error(`${ctx("temperature")}: must be a number`);
+    partial.temperature = raw.temperature;
+  }
+  if (raw.consensus !== void 0) {
+    if (typeof raw.consensus !== "number") throw new Error(`${ctx("consensus")}: must be a number`);
+    partial.consensus = raw.consensus;
+  }
+  if (raw.max_tokens !== void 0) {
+    if (typeof raw.max_tokens !== "number" && raw.max_tokens !== "auto") {
+      throw new Error(`${ctx("max_tokens")}: must be a number or 'auto'`);
+    }
+    partial.max_tokens = raw.max_tokens;
+  }
   return Object.keys(partial).length > 0 ? partial : void 0;
 }
 function mergeLlmConfig(base, secrets) {
@@ -5766,7 +6380,7 @@ function buildTransitiveChains(targetNode, direct, allDependents, reverse) {
   }
   return chains.sort();
 }
-function collectDescendants(graph, nodePath) {
+function collectDescendants2(graph, nodePath) {
   const node = graph.nodes.get(nodePath);
   if (!node) return [];
   const result = [];
@@ -5920,7 +6534,7 @@ async function handleFlowImpact(graph, flowName) {
   for (const nodePath of flow.nodes) {
     if (graph.nodes.has(nodePath)) {
       participants.add(nodePath);
-      for (const desc of collectDescendants(graph, nodePath)) {
+      for (const desc of collectDescendants2(graph, nodePath)) {
         participants.add(desc);
       }
     }
@@ -6096,7 +6710,7 @@ function registerImpactCommand(program2) {
 `);
           }
         }
-        const descendants = collectDescendants(graph, nodePath);
+        const descendants = collectDescendants2(graph, nodePath);
         if (descendants.length > 0) {
           process.stdout.write("\nDescendants (hierarchy impact):\n");
           for (const desc of descendants) {