@chrisdudek/yg 2.3.3 → 2.4.0

package/dist/bin.js

@@ -78,11 +78,10 @@ BEFORE reading, researching, planning, OR modifying ANY mapped file:
      - Understanding how/why it works \u2192 yg build-context --node <owner>
      - Assessing what is affected by a change \u2192 yg impact --node <owner>
      - Planning modifications \u2192 both (build-context first, then impact)
-  The context package is your primary source of ARCHITECTURAL understanding:
-  intent, constraints, relations, rationale. For IMPLEMENTATION precision
-  (exact behavior, error handling, await patterns, edge cases) \u2014 verify
-  against source code. Aspects describe intended patterns; individual
-  implementations may deviate.
+  \`yg build-context --node <path>\`. Read the YAML map for topology,
+  then read artifact files listed in the artifacts section. For quick
+  orientation, the map alone is sufficient. For implementation, read
+  all artifact files before changing code.
   If the context package seems insufficient \u2014 enrich the graph.
 
 AFTER modifying:
@@ -107,7 +106,7 @@ WHEN UNSURE: ask the user. Never guess. Never assume.
 ### Five Core Rules
 
 1. **Graph first.** Before reading, researching, planning, or modifying mapped files, run \`yg owner\` and the appropriate graph tool: \`yg build-context\` to understand a component, \`yg impact\` to assess blast radius. The graph is your primary source of architectural understanding. For implementation-level precision (exact behavior, error paths, edge cases) \u2014 verify against source code after loading the context package.
-2. **Code and graph are one.** Code changed \u2192 graph updated in the same response. Graph changed \u2192 source verified in the same response. No exceptions.
+2. **The graph is the specification; code implements it.** The graph absorbs knowledge from every source \u2014 external docs, conversations, decisions \u2014 and must be self-sufficient. If all other sources disappeared, the graph alone must contain enough to understand the system. Do not leave knowledge in external documents and reference them \u2014 capture the knowledge in graph artifacts. Update graph artifacts immediately after each file change, while context is fresh \u2014 do not batch graph updates to the end of a task. Code and graph move together: code changed \u2192 graph updated before moving to the next file. Graph changed \u2192 source verified in the same response. When planning work \u2014 in any tool, skill, or workflow \u2014 graph updates are part of each step's definition of done, never a separate phase.
 3. **Never invent why.** The graph captures human intent. If you don't know why something was decided, ask. Never hallucinate rationale.
 4. **Always capture why \u2014 especially why NOT.** When the user explains a reason, record it in the graph immediately. When a design choice is made, also record rejected alternatives: "Chose X over Y because Z." Rejected alternatives are the highest-value information \u2014 invisible in code and irrecoverable once forgotten. Conversation evaporates; graph persists.
 5. **Ask before resolving ambiguity.** When multiple valid interpretations exist, stop, list options, ask the user. Never silently choose.
@@ -154,7 +153,7 @@ What matters is the ACTION you are performing, not what instructed it. If the ac
 You have broken Yggdrasil if you do any of the following:
 
 - \u274C Worked on a mapped file without running \`yg owner\` + the appropriate graph tool (\`build-context\` or \`impact\`) first \u2014 regardless of what instructed the action (skill, plan, user request, workflow step).
-- \u274C Modified source code without updating graph artifacts in the same response, or vice versa.
+- \u274C Modified source code without updating graph artifacts before moving to the next file, or vice versa.
 - \u274C Resolved a code-graph inconsistency or ambiguity without asking the user first.
 - \u274C Created or edited a graph element without reading its schema in \`schemas/\` first.
 - \u274C Ran \`yg drift-sync\` before both graph artifacts and source code are current.
@@ -188,9 +187,13 @@ Include this as the FIRST instruction in every subagent prompt:
 
 \`\`\`
 BEFORE doing anything else: read .yggdrasil/agent-rules.md and follow its protocol.
+DELIVERABLES \u2014 all required, incomplete work will be rejected:
+  1. Working source code
+  2. Graph nodes with artifacts for every new/modified source file
+  3. \`yg validate\` passing
 \`\`\`
 
-A subagent that skips this step will read code without graph context, miss architectural constraints, and produce changes that break graph-code consistency.`;
+A subagent that delivers code without corresponding graph updates has not completed its task. Before accepting subagent output, verify: are there new or modified source files without corresponding graph coverage? If yes, the work is incomplete.`;
 var OPERATIONS = `## OPERATIONS
 
 ### Conversation Lifecycle
@@ -204,7 +207,10 @@ PREFLIGHT (every conversation, before any work):
 
 UNDERSTANDING mapped code (questions, research, OR planning):
   - [ ] 1. yg owner --file <path>
-  - [ ] 2. Owner found \u2192 yg build-context --node <path>. Use context package as primary source.
+  - [ ] 2. Owner found \u2192 yg build-context --node <path>. Read the YAML map
+         for topology, then read artifact files from the artifacts section.
+         For quick orientation, the map alone is sufficient. For implementation,
+         read all artifact files before changing code.
   - [ ] 3. Owner not found \u2192 use file analysis, state it is not graph-backed.
   Never use grep or raw file reads as primary understanding when graph coverage exists.
   Raw reads supplement the context package \u2014 they do not replace it.
@@ -216,7 +222,7 @@ WRAP-UP (user signals "done", "wrap up", "that's enough"):
 
 BEFORE ENDING ANY RESPONSE (self-audit):
   - [ ] Did I interact with mapped code (read, research, or modify)? If yes \u2192 did I use a graph tool BEFORE reading source?
-  - [ ] Did I modify source code? If yes \u2192 did I update graph artifacts in this same response?
+  - [ ] Did I modify source code? If yes \u2192 did I update graph artifacts before moving to the next file?
   - [ ] If you broke either rule, you have broken the protocol. Do not finish until both are fixed.
 \`\`\`
 
@@ -231,7 +237,7 @@ You are not allowed to edit or create source code without establishing graph cov
 - [ ] 1. Read specification: \`yg build-context --node <node_path>\`
 - [ ] 2. Assess blast radius: \`yg impact --node <node_path>\` \u2014 review dependents, descendants, and co-aspect nodes before changing interfaces or shared behavior
 - [ ] 3. Modify source code
-- [ ] 4. Sync graph artifacts \u2014 edit artifact files to reflect the changes
+- [ ] 4. Sync graph artifacts \u2014 edit artifact files to reflect the changes (after each file, not batched \u2014 context is freshest immediately after the change)
 - [ ] 5. Run \`yg validate\` \u2014 fix all errors (if unfixable after 3 attempts \u2192 stop, report to user)
 - [ ] 6. Run \`yg drift-sync --node <node_path>\` \u2014 only after graph and code are both current
 
@@ -380,7 +386,13 @@ Projects can define additional artifact types in \`yg-config.yaml\` under \`arti
 
 ### Context Assembly
 
-Run \`yg build-context --node <path>\` to get the deterministic context package for a node. The package assembles global project identity, hierarchy, own artifacts, aspects, and relational context. It is your architectural map. For implementation-level claims (exact call patterns, error handling, await vs fire-and-forget) \u2014 verify against source code. If the package is insufficient, enrich the graph.
+**Reading context:** \`yg build-context --node <path>\` returns a YAML map with the node's topology (hierarchy, dependencies, aspects, flows) and an \`artifacts\` section listing files to read. All artifact paths are relative to \`.yggdrasil/\` \u2014 construct full path as \`.yggdrasil/<path>\`.
+
+**Default mode (paths-only):** Use for all graph operations. Read the YAML map first to understand topology. Then read artifact files from the \`artifacts\` section using the Read tool. For quick orientation (scoping, blast radius assessment), the map alone is sufficient. For implementation or modification, read all artifact files before changing code.
+
+**Full mode (\`--full\`):** Use only when you cannot read files individually \u2014 e.g., when pasting context into a prompt, sharing with a user, or when you have no Read tool available.
+
+Artifact paths are stable identifiers within a session. When building context for multiple nodes, skip reading files you have already read \u2014 same path means same content.
 
 ### Information Routing
 
@@ -450,7 +462,8 @@ Test: "Does this describe what happens in the world, or only in the software?" I
 \`\`\`
 yg preflight [--quick]              Unified diagnostic: drift + status + validate.
 yg owner --file <path>              Find the node that owns this file.
-yg build-context --node <path>      Assemble context package for this node.
+yg build-context --node <path>      Assemble context map with artifact paths (default).
+yg build-context --node <path> --full  Same map + file contents appended below separator.
 yg tree [--root <path>] [--depth N] Print graph structure.
 yg aspects                          List aspects with metadata (YAML output).
 yg flows                            List flows with metadata (YAML output).
@@ -1156,6 +1169,10 @@ function registerInitCommand(program2) {
   });
 }
 
+// src/cli/build-context.ts
+import { readFile as readFile14 } from "fs/promises";
+import path12 from "path";
+
 // src/core/graph-loader.ts
 import { readdir as readdir4, readFile as readFile11 } from "fs/promises";
 import path9 from "path";
@@ -2026,6 +2043,150 @@ function collectAncestors(node) {
   }
   return ancestors;
 }
+function toContextMapOutput(pkg2, graph) {
+  const node = graph.nodes.get(pkg2.nodePath);
+  const config = graph.config;
+  const nodeAspects = (node.meta.aspects ?? []).map((entry) => {
+    const ref = { id: entry.aspect };
+    if (entry.anchors?.length) ref.anchors = entry.anchors;
+    if (entry.exceptions?.length) ref.exceptions = entry.exceptions;
+    return ref;
+  });
+  const participatingFlows = collectParticipatingFlows(graph, node);
+  const flowRefs = participatingFlows.map((f) => {
+    const ref = { path: f.path, name: f.name };
+    if (f.aspects?.length) ref.aspects = f.aspects;
+    return ref;
+  });
+  const ancestors = collectAncestors(node);
+  const hierarchyRefs = ancestors.map((a) => {
+    const nodeAspectIds = (a.meta.aspects ?? []).map((e) => e.aspect);
+    const expanded = expandAspects(nodeAspectIds, graph.aspects);
+    return { path: a.path, name: a.meta.name, type: a.meta.type, aspects: expanded };
+  });
+  const ancestorPaths = new Set(ancestors.map((a) => a.path));
+  const depRefs = [];
+  for (const relation of node.meta.relations ?? []) {
+    const target = graph.nodes.get(relation.target);
+    if (!target) continue;
+    if (ancestorPaths.has(relation.target)) continue;
+    const depAncestors = collectAncestors(target);
+    const depHierarchy = depAncestors.map((a) => {
+      const ids = (a.meta.aspects ?? []).map((e) => e.aspect);
+      const expanded = expandAspects(ids, graph.aspects);
+      return { path: a.path, name: a.meta.name, type: a.meta.type, aspects: expanded };
+    });
+    const depEffectiveAspects = [...collectEffectiveAspectIds(graph, target.path)];
+    const ref = {
+      path: target.path,
+      name: target.meta.name,
+      type: target.meta.type,
+      relation: relation.type,
+      aspects: depEffectiveAspects,
+      hierarchy: depHierarchy
+    };
+    if (relation.consumes?.length) ref.consumes = relation.consumes;
+    if (relation.failure) ref.failure = relation.failure;
+    if (relation.event_name) ref["event-name"] = relation.event_name;
+    depRefs.push(ref);
+  }
+  const registry = buildArtifactRegistry(node, ancestors, depRefs, graph);
+  const warningThreshold = config.quality?.context_budget?.warning ?? 1e4;
+  const errorThreshold = config.quality?.context_budget?.error ?? 2e4;
+  const budgetStatus = pkg2.tokenCount >= errorThreshold ? "error" : pkg2.tokenCount >= warningThreshold ? "warning" : "ok";
+  return {
+    meta: { tokenCount: pkg2.tokenCount, budgetStatus },
+    project: config.name,
+    node: {
+      path: pkg2.nodePath,
+      name: pkg2.nodeName,
+      type: node.meta.type,
+      mappings: normalizeMappingPaths(node.meta.mapping),
+      aspects: nodeAspects,
+      flows: flowRefs
+    },
+    hierarchy: hierarchyRefs,
+    dependencies: depRefs,
+    artifacts: registry
+  };
+}
+function buildArtifactRegistry(node, ancestors, dependencies, graph) {
+  const config = graph.config;
+  const configArtifactKeys = new Set(Object.keys(config.artifacts ?? {}));
+  const structuralFilenames = Object.entries(config.artifacts ?? {}).filter(([, c]) => c.included_in_relations).map(([filename]) => filename);
+  const nodes = {};
+  const aspects = {};
+  const flows = {};
+  function addNodeEntry(n, includeYgNodeYaml, filter) {
+    if (nodes[n.path]) return;
+    const files = [];
+    if (includeYgNodeYaml) {
+      files.push(`model/${n.path}/yg-node.yaml`);
+    }
+    for (const filename of filter) {
+      if (n.artifacts.some((a) => a.filename === filename)) {
+        files.push(`model/${n.path}/${filename}`);
+      }
+    }
+    if (files.length > 0) {
+      nodes[n.path] = { files };
+    }
+  }
+  addNodeEntry(node, true, [...configArtifactKeys]);
+  for (const ancestor of ancestors) {
+    addNodeEntry(ancestor, true, [...configArtifactKeys]);
+  }
+  const seenDepAncestors = /* @__PURE__ */ new Set([node.path, ...ancestors.map((a) => a.path)]);
+  for (const dep of dependencies) {
+    const target = graph.nodes.get(dep.path);
+    if (target) {
+      addNodeEntry(target, false, structuralFilenames);
+    }
+    for (const ancestor of dep.hierarchy) {
+      if (seenDepAncestors.has(ancestor.path)) continue;
+      seenDepAncestors.add(ancestor.path);
+      const ancestorNode = graph.nodes.get(ancestor.path);
+      if (ancestorNode) {
+        addNodeEntry(ancestorNode, false, structuralFilenames);
+      }
+    }
+  }
+  const allAspectIds = collectEffectiveAspectIds(graph, node.path);
+  for (const dep of dependencies) {
+    for (const id of dep.aspects) {
+      allAspectIds.add(id);
+    }
+  }
+  const resolvedAspects = resolveAspects(allAspectIds, graph.aspects);
+  for (const aspect of resolvedAspects) {
+    const files = [];
+    files.push(`aspects/${aspect.id}/yg-aspect.yaml`);
+    for (const art of aspect.artifacts) {
+      files.push(`aspects/${aspect.id}/${art.filename}`);
+    }
+    const entry = {
+      name: aspect.name,
+      files
+    };
+    if (aspect.implies?.length) entry.implies = aspect.implies;
+    aspects[aspect.id] = entry;
+  }
+  const participatingFlows = collectParticipatingFlows(graph, node);
+  for (const flow of participatingFlows) {
+    const files = [];
+    files.push(`flows/${flow.path}/yg-flow.yaml`);
+    for (const art of flow.artifacts) {
+      files.push(`flows/${flow.path}/${art.filename}`);
+    }
+    const entry = {
+      name: flow.name,
+      files
+    };
+    if (flow.aspects?.length) entry.aspects = flow.aspects;
+    flows[flow.path] = entry;
+  }
+  return { nodes, aspects, flows };
+}
 function collectEffectiveAspectIds(graph, nodePath) {
   const node = graph.nodes.get(nodePath);
   if (!node) return /* @__PURE__ */ new Set();
@@ -2044,6 +2205,38 @@ function collectEffectiveAspectIds(graph, nodePath) {
   return new Set(expandAspects([...raw], graph.aspects));
 }
 
+// src/formatters/context-text.ts
+import { stringify } from "yaml";
+function formatContextYaml(data) {
+  const output = {
+    meta: {
+      "token-count": data.meta.tokenCount,
+      "budget-status": data.meta.budgetStatus
+    },
+    project: data.project,
+    node: data.node,
+    hierarchy: data.hierarchy.length > 0 ? data.hierarchy : void 0,
+    dependencies: data.dependencies.length > 0 ? data.dependencies : void 0,
+    artifacts: data.artifacts
+  };
+  for (const key of Object.keys(output)) {
+    if (output[key] === void 0) delete output[key];
+  }
+  return stringify(output, { lineWidth: 0 });
+}
+function formatFullContent(files) {
+  if (files.length === 0) return "";
+  let out = "---\n\n";
+  for (const file of files) {
+    out += `<${file.path}>
+${file.content}
+</${file.path}>
+
+`;
+  }
+  return out;
+}
+
 // src/core/validator.ts
 import { readdir as readdir5, readFile as readFile13, stat as stat4 } from "fs/promises";
 import path11 from "path";
@@ -2796,78 +2989,6 @@ async function checkContextBudget(graph) {
   return issues;
 }
 
-// src/formatters/context-text.ts
-function escapeAttr(val) {
-  return val.replace(/"/g, "&quot;");
-}
-function formatLayer(layer) {
-  switch (layer.type) {
-    case "global":
-      return `<global>
-${layer.content}
-</global>`;
-    case "hierarchy": {
-      const pathMatch = layer.label.match(/\((.+)\/\)/);
-      const pathAttr = pathMatch ? ` path="${escapeAttr(pathMatch[1])}"` : "";
-      const aspectsAttr = layer.attrs?.aspects ? ` aspects="${escapeAttr(layer.attrs.aspects)}"` : "";
-      return `<hierarchy${pathAttr}${aspectsAttr}>
-${layer.content}
-</hierarchy>`;
-    }
-    case "own": {
-      if (layer.label === "Materialization Target") {
-        return `<materialization-target paths="${escapeAttr(layer.content)}" />`;
-      }
-      const ownAspectsAttr = layer.attrs?.aspects ? ` aspects="${escapeAttr(layer.attrs.aspects)}"` : "";
-      return `<own-artifacts${ownAspectsAttr}>
-${layer.content}
-</own-artifacts>`;
-    }
-    case "aspects": {
-      const nameMatch = layer.label.match(/^(.+?) \(aspect: (.+)\)$/);
-      const name = nameMatch ? escapeAttr(nameMatch[1]) : "";
-      const id = nameMatch ? escapeAttr(nameMatch[2]) : "";
-      return `<aspect name="${name}" id="${id}">
-${layer.content}
-</aspect>`;
-    }
-    case "relational": {
-      const attrs = layer.attrs ?? {};
-      const attrStr = Object.entries(attrs).map(([k, v]) => ` ${k}="${escapeAttr(v)}"`).join("");
-      const tagName = attrs.type && ["emits", "listens"].includes(attrs.type) ? "event" : "dependency";
-      return `<${tagName}${attrStr}>
-${layer.content}
-</${tagName}>`;
-    }
-    case "flows": {
-      const flowName = layer.label.replace(/^Flow: /, "").trim();
-      const flowAspectsAttr = layer.attrs?.aspects ? ` aspects="${escapeAttr(layer.attrs.aspects)}"` : "";
-      return `<flow name="${escapeAttr(flowName)}"${flowAspectsAttr}>
-${layer.content}
-</flow>`;
-    }
-    default:
-      return layer.content;
-  }
-}
-function formatContextText(pkg2) {
-  const attrs = [
-    `node-path="${escapeAttr(pkg2.nodePath)}"`,
-    `node-name="${escapeAttr(pkg2.nodeName)}"`,
-    `token-count="${pkg2.tokenCount}"`
-  ].join(" ");
-  let out = `<context-package ${attrs}>
-
-`;
-  for (const section of pkg2.sections) {
-    for (const layer of section.layers) {
-      out += formatLayer(layer) + "\n\n";
-    }
-  }
-  out += "</context-package>";
-  return out;
-}
-
 // src/cli/build-context.ts
 function collectRelevantNodePaths(graph, nodePath) {
   const relevant = /* @__PURE__ */ new Set();
@@ -2879,19 +3000,24 @@ function collectRelevantNodePaths(graph, nodePath) {
   }
   for (const rel of node.meta.relations ?? []) {
     relevant.add(rel.target);
+    const target = graph.nodes.get(rel.target);
+    if (target) {
+      for (const ancestor of collectAncestors(target)) {
+        relevant.add(ancestor.path);
+      }
+    }
   }
   return relevant;
 }
 function registerBuildCommand(program2) {
-  program2.command("build-context").description("Assemble a context package for one node").requiredOption("--node <node-path>", "Node path relative to .yggdrasil/model/").action(async (options) => {
+  program2.command("build-context").description("Assemble a context package for one node").requiredOption("--node <node-path>", "Node path relative to .yggdrasil/model/").option("--full", "Include artifact file contents in output").action(async (options) => {
     try {
       const graph = await loadGraph(process.cwd());
       const nodePath = options.node.trim().replace(/^\.\//, "").replace(/\/$/, "");
       const relevantNodes = collectRelevantNodePaths(graph, nodePath);
       const validationResult = await validate(graph, "all");
       const relevantErrors = validationResult.issues.filter(
-        (issue) => issue.severity === "error" && // Global errors (no nodePath) always block — e.g., E012 invalid config
-        (!issue.nodePath || relevantNodes.has(issue.nodePath))
+        (issue) => issue.severity === "error" && (!issue.nodePath || relevantNodes.has(issue.nodePath))
       );
       if (relevantErrors.length > 0) {
         const totalErrors = validationResult.issues.filter((i) => i.severity === "error").length;
@@ -2911,19 +3037,29 @@ function registerBuildCommand(program2) {
         process.exit(1);
       }
       const pkg2 = await buildContext(graph, nodePath);
-      const warningThreshold = graph.config.quality?.context_budget.warning ?? 1e4;
-      const errorThreshold = graph.config.quality?.context_budget.error ?? 2e4;
-      const budgetStatus = pkg2.tokenCount >= errorThreshold ? "error" : pkg2.tokenCount >= warningThreshold ? "warning" : "ok";
-      let output = formatContextText(pkg2);
-      output += `Budget status: ${budgetStatus}
-`;
-      process.stdout.write(output);
-      if (budgetStatus === "error") {
-        process.stderr.write(
-          `Warning: context package exceeds error budget (${pkg2.tokenCount} >= ${errorThreshold}). Consider splitting the node.
-`
-        );
+      const mapOutput = toContextMapOutput(pkg2, graph);
+      let output = formatContextYaml(mapOutput);
+      if (options.full) {
+        const allFiles = [];
+        const allEntries = [
+          ...Object.values(mapOutput.artifacts.nodes),
+          ...Object.values(mapOutput.artifacts.aspects),
+          ...Object.values(mapOutput.artifacts.flows)
+        ];
+        const seen = /* @__PURE__ */ new Set();
+        for (const entry of allEntries) {
+          for (const filePath of entry.files) {
+            if (seen.has(filePath)) continue;
+            seen.add(filePath);
+            const content = await findFileContent(filePath, graph);
+            if (content !== void 0) {
+              allFiles.push({ path: filePath, content });
+            }
+          }
+        }
+        output += formatFullContent(allFiles);
       }
+      process.stdout.write(output);
     } catch (error) {
       process.stderr.write(`Error: ${error.message}
 `);
@@ -2931,6 +3067,56 @@ function registerBuildCommand(program2) {
     }
   });
 }
+async function findFileContent(filePath, graph) {
+  async function readYamlFromDisk(relativePath) {
+    try {
+      const fullPath = path12.join(graph.rootPath, relativePath);
+      return (await readFile14(fullPath, "utf-8")).trim();
+    } catch {
+      return void 0;
+    }
+  }
+  if (filePath.startsWith("model/")) {
+    const rest = filePath.slice("model/".length);
+    const parts = rest.split("/");
+    const filename = parts.pop();
+    const nodePath = parts.join("/");
+    const node = graph.nodes.get(nodePath);
+    if (!node) return void 0;
+    if (filename === "yg-node.yaml") {
+      return node.nodeYamlRaw?.trim() ?? await readYamlFromDisk(filePath);
+    }
+    const art = node.artifacts.find((a) => a.filename === filename);
+    return art?.content;
+  }
+  if (filePath.startsWith("aspects/")) {
+    const rest = filePath.slice("aspects/".length);
+    const parts = rest.split("/");
+    const aspectId = parts[0];
+    const filename = parts.slice(1).join("/");
+    const aspect = graph.aspects.find((a) => a.id === aspectId);
+    if (!aspect) return void 0;
+    if (filename === "yg-aspect.yaml") {
+      return readYamlFromDisk(filePath);
+    }
+    const art = aspect.artifacts.find((a) => a.filename === filename);
+    return art?.content;
+  }
+  if (filePath.startsWith("flows/")) {
+    const rest = filePath.slice("flows/".length);
+    const parts = rest.split("/");
+    const flowPath = parts[0];
+    const filename = parts.slice(1).join("/");
+    const flow = graph.flows.find((f) => f.path === flowPath);
+    if (!flow) return void 0;
+    if (filename === "yg-flow.yaml") {
+      return readYamlFromDisk(filePath);
+    }
+    const art = flow.artifacts.find((a) => a.filename === filename);
+    return art?.content;
+  }
+  return void 0;
+}
 
 // src/cli/validate.ts
 import chalk from "chalk";
@@ -2981,12 +3167,12 @@ ${errors.length} errors, ${warnings.length} warnings.
 import chalk2 from "chalk";
 
 // src/io/drift-state-store.ts
-import { readFile as readFile14, writeFile as writeFile5, stat as stat5, readdir as readdir6, mkdir as mkdir3, rm as rm2 } from "fs/promises";
-import path12 from "path";
+import { readFile as readFile15, writeFile as writeFile5, stat as stat5, readdir as readdir6, mkdir as mkdir3, rm as rm2 } from "fs/promises";
+import path13 from "path";
 import { parse as yamlParse } from "yaml";
 var DRIFT_STATE_DIR = ".drift-state";
 function nodeStatePath(yggRoot, nodePath) {
-  return path12.join(yggRoot, DRIFT_STATE_DIR, `${nodePath}.json`);
+  return path13.join(yggRoot, DRIFT_STATE_DIR, `${nodePath}.json`);
 }
 async function scanJsonFiles(dir, baseDir) {
   const results = [];
@@ -2997,12 +3183,12 @@ async function scanJsonFiles(dir, baseDir) {
     return results;
   }
   for (const entry of entries) {
-    const fullPath = path12.join(dir, entry.name);
+    const fullPath = path13.join(dir, entry.name);
     if (entry.isDirectory()) {
       const nested = await scanJsonFiles(fullPath, baseDir);
       results.push(...nested);
     } else if (entry.isFile() && entry.name.endsWith(".json")) {
-      const relPath = path12.relative(baseDir, fullPath);
+      const relPath = path13.relative(baseDir, fullPath);
       const nodePath = relPath.replace(/\\/g, "/").replace(/\.json$/, "");
       results.push(nodePath);
     }
@@ -3010,13 +3196,13 @@ async function scanJsonFiles(dir, baseDir) {
   return results;
 }
 async function removeEmptyParents(filePath, stopDir) {
-  let dir = path12.dirname(filePath);
+  let dir = path13.dirname(filePath);
   while (dir !== stopDir && dir.startsWith(stopDir)) {
     try {
       const entries = await readdir6(dir);
       if (entries.length === 0) {
         await rm2(dir, { recursive: true });
-        dir = path12.dirname(dir);
+        dir = path13.dirname(dir);
       } else {
         break;
       }
@@ -3028,7 +3214,7 @@ async function removeEmptyParents(filePath, stopDir) {
 async function readNodeDriftState(yggRoot, nodePath) {
   try {
     const filePath = nodeStatePath(yggRoot, nodePath);
-    const content = await readFile14(filePath, "utf-8");
+    const content = await readFile15(filePath, "utf-8");
     const parsed = JSON.parse(content);
     return parsed;
   } catch {
@@ -3037,12 +3223,12 @@ async function readNodeDriftState(yggRoot, nodePath) {
 }
 async function writeNodeDriftState(yggRoot, nodePath, nodeState) {
   const filePath = nodeStatePath(yggRoot, nodePath);
-  await mkdir3(path12.dirname(filePath), { recursive: true });
+  await mkdir3(path13.dirname(filePath), { recursive: true });
   const content = JSON.stringify(nodeState, null, 2) + "\n";
   await writeFile5(filePath, content, "utf-8");
 }
 async function garbageCollectDriftState(yggRoot, validNodePaths) {
-  const driftDir = path12.join(yggRoot, DRIFT_STATE_DIR);
+  const driftDir = path13.join(yggRoot, DRIFT_STATE_DIR);
   const allNodePaths = await scanJsonFiles(driftDir, driftDir);
   const removed = [];
   for (const nodePath of allNodePaths) {
@@ -3056,7 +3242,7 @@ async function garbageCollectDriftState(yggRoot, validNodePaths) {
   return removed.sort();
 }
 async function readDriftState(yggRoot) {
-  const driftPath = path12.join(yggRoot, DRIFT_STATE_DIR);
+  const driftPath = path13.join(yggRoot, DRIFT_STATE_DIR);
   let driftStat;
   try {
     driftStat = await stat5(driftPath);
@@ -3064,7 +3250,7 @@ async function readDriftState(yggRoot) {
     return {};
   }
   if (driftStat.isFile()) {
-    const content = await readFile14(driftPath, "utf-8");
+    const content = await readFile15(driftPath, "utf-8");
     let raw;
     try {
       raw = JSON.parse(content);
@@ -3096,20 +3282,20 @@ async function readDriftState(yggRoot) {
 }
 
 // src/utils/hash.ts
-import { readFile as readFile15, readdir as readdir7, stat as stat6 } from "fs/promises";
-import path13 from "path";
+import { readFile as readFile16, readdir as readdir7, stat as stat6 } from "fs/promises";
+import path14 from "path";
 import { createHash } from "crypto";
 import { createRequire } from "module";
 var require2 = createRequire(import.meta.url);
 var ignoreFactory = require2("ignore");
 async function hashFile(filePath) {
-  const content = await readFile15(filePath);
+  const content = await readFile16(filePath);
   return createHash("sha256").update(content).digest("hex");
 }
 async function loadRootGitignoreStack(projectRoot) {
   if (!projectRoot) return [];
   try {
-    const content = await readFile15(path13.join(projectRoot, ".gitignore"), "utf-8");
+    const content = await readFile16(path14.join(projectRoot, ".gitignore"), "utf-8");
     const matcher = ignoreFactory();
     matcher.add(content);
     return [{ basePath: projectRoot, matcher }];
@@ -3119,7 +3305,7 @@ async function loadRootGitignoreStack(projectRoot) {
 }
 function isIgnoredByStack(candidatePath, stack) {
   for (const { basePath, matcher } of stack) {
-    const relativePath = path13.relative(basePath, candidatePath);
+    const relativePath = path14.relative(basePath, candidatePath);
     if (relativePath === "" || relativePath.startsWith("..")) continue;
     if (matcher.ignores(relativePath) || matcher.ignores(relativePath + "/")) return true;
   }
@@ -3134,7 +3320,7 @@ async function hashTrackedFiles(projectRoot, trackedFiles, storedFileData, exclu
   const gitignoreStack = await loadRootGitignoreStack(projectRoot);
   const allFiles = [];
   for (const tf of trackedFiles) {
-    const absPath = path13.join(projectRoot, tf.path);
+    const absPath = path14.join(projectRoot, tf.path);
     try {
       const st = await stat6(absPath);
       if (st.isDirectory()) {
@@ -3144,7 +3330,7 @@ async function hashTrackedFiles(projectRoot, trackedFiles, storedFileData, exclu
         });
         for (const entry of dirEntries) {
           allFiles.push({
-            relPath: path13.join(tf.path, entry.relPath).replace(/\\/g, "/"),
+            relPath: path14.join(tf.path, entry.relPath).replace(/\\/g, "/"),
             absPath: entry.absPath,
             mtimeMs: entry.mtimeMs
           });
@@ -3184,7 +3370,7 @@ async function hashTrackedFiles(projectRoot, trackedFiles, storedFileData, exclu
 async function collectDirectoryFilePaths(directoryPath, rootDirectoryPath, options) {
   let stack = options.gitignoreStack ?? [];
   try {
-    const localContent = await readFile15(path13.join(directoryPath, ".gitignore"), "utf-8");
+    const localContent = await readFile16(path14.join(directoryPath, ".gitignore"), "utf-8");
     const localMatcher = ignoreFactory();
     localMatcher.add(localContent);
     stack = [...stack, { basePath: directoryPath, matcher: localMatcher }];
@@ -3194,7 +3380,7 @@ async function collectDirectoryFilePaths(directoryPath, rootDirectoryPath, optio
   const dirs = [];
   const files = [];
   for (const entry of entries) {
-    const absoluteChildPath = path13.join(directoryPath, entry.name);
+    const absoluteChildPath = path14.join(directoryPath, entry.name);
     if (isIgnoredByStack(absoluteChildPath, stack)) continue;
     if (entry.isDirectory()) dirs.push(absoluteChildPath);
     else if (entry.isFile()) files.push(absoluteChildPath);
@@ -3207,7 +3393,7 @@ async function collectDirectoryFilePaths(directoryPath, rootDirectoryPath, optio
     Promise.all(files.map(async (f) => {
       const fileStat = await stat6(f);
       return {
-        relPath: path13.relative(rootDirectoryPath, f),
+        relPath: path14.relative(rootDirectoryPath, f),
         absPath: f,
         mtimeMs: fileStat.mtimeMs
       };
@@ -3220,14 +3406,14 @@ async function collectDirectoryFilePaths(directoryPath, rootDirectoryPath, optio
 }
 
 // src/core/context-files.ts
-import path14 from "path";
+import path15 from "path";
 var STRUCTURAL_RELATION_TYPES2 = /* @__PURE__ */ new Set(["uses", "calls", "extends", "implements"]);
 function collectTrackedFiles(node, graph) {
   const seen = /* @__PURE__ */ new Set();
   const result = [];
-  const projectRoot = path14.dirname(graph.rootPath);
-  const yggPrefix = path14.relative(projectRoot, graph.rootPath);
-  const yggPrefixNormalized = yggPrefix.split(path14.sep).join("/");
+  const projectRoot = path15.dirname(graph.rootPath);
+  const yggPrefix = path15.relative(projectRoot, graph.rootPath);
+  const yggPrefixNormalized = yggPrefix.split(path15.sep).join("/");
   const configArtifactKeys = new Set(Object.keys(graph.config.artifacts ?? {}));
   function addFile(filePath, category) {
     if (seen.has(filePath)) return;
@@ -3291,6 +3477,35 @@ function collectTrackedFiles(node, graph) {
         }
       }
     }
+    const depAncestors = collectAncestors(target);
+    for (const ancestor of depAncestors) {
+      const filterFilenames = structuralFilenames.length > 0 ? structuralFilenames : [...configArtifactKeys];
+      for (const filename of filterFilenames) {
+        if (ancestor.artifacts.some((a) => a.filename === filename)) {
+          addFile(graphPath("model", ancestor.path, filename), "graph");
+        }
+      }
+    }
+  }
+  for (const relation of node.meta.relations ?? []) {
+    if (relation.type !== "emits" && relation.type !== "listens") continue;
+    const target = graph.nodes.get(relation.target);
+    if (!target) continue;
+    const structuralFilenames = Object.entries(graph.config.artifacts ?? {}).filter(([, c]) => c.included_in_relations).map(([filename]) => filename);
+    const filterFilenames = structuralFilenames.length > 0 ? structuralFilenames : [...configArtifactKeys];
+    for (const filename of filterFilenames) {
+      if (target.artifacts.some((a) => a.filename === filename)) {
+        addFile(graphPath("model", target.path, filename), "graph");
+      }
+    }
+    const eventAncestors = collectAncestors(target);
+    for (const ancestor of eventAncestors) {
+      for (const filename of filterFilenames) {
+        if (ancestor.artifacts.some((a) => a.filename === filename)) {
+          addFile(graphPath("model", ancestor.path, filename), "graph");
+        }
+      }
+    }
   }
   for (const flow of participatingFlows) {
     addFile(graphPath("flows", flow.path, "yg-flow.yaml"), "graph");
@@ -3311,7 +3526,7 @@ function collectParticipatingFlows2(graph, node, ancestors) {
 
 // src/core/drift-detector.ts
 import { access as access2 } from "fs/promises";
-import path15 from "path";
+import path16 from "path";
 function getChildMappingExclusions(graph, nodePath) {
   const node = graph.nodes.get(nodePath);
   if (!node) return [];
@@ -3333,7 +3548,7 @@ function getChildMappingExclusions(graph, nodePath) {
   return exclusions;
 }
 async function detectDrift(graph, filterNodePath) {
-  const projectRoot = path15.dirname(graph.rootPath);
+  const projectRoot = path16.dirname(graph.rootPath);
   const driftState = await readDriftState(graph.rootPath);
   const entries = [];
   for (const [nodePath, node] of graph.nodes) {
@@ -3415,14 +3630,14 @@ async function detectDrift(graph, filterNodePath) {
   };
 }
 function categorizeFile(filePath, _rootPath, projectRoot) {
-  const yggPrefix = path15.relative(projectRoot, _rootPath);
-  const normalizedPrefix = yggPrefix.split(path15.sep).join("/");
+  const yggPrefix = path16.relative(projectRoot, _rootPath);
+  const normalizedPrefix = yggPrefix.split(path16.sep).join("/");
   const normalizedFilePath = filePath.replace(/\\/g, "/");
   return normalizedFilePath.startsWith(normalizedPrefix) ? "graph" : "source";
 }
 async function allPathsMissing(projectRoot, mappingPaths) {
   for (const mp of mappingPaths) {
-    const absPath = path15.join(projectRoot, mp);
+    const absPath = path16.join(projectRoot, mp);
     try {
       await access2(absPath);
       return false;
@@ -3432,7 +3647,7 @@ async function allPathsMissing(projectRoot, mappingPaths) {
   return true;
 }
 async function syncDriftState(graph, nodePath) {
-  const projectRoot = path15.dirname(graph.rootPath);
+  const projectRoot = path16.dirname(graph.rootPath);
   const node = graph.nodes.get(nodePath);
   if (!node) throw new Error(`Node not found: ${nodePath}`);
   if (!node.meta.mapping) throw new Error(`Node has no mapping: ${nodePath}`);
@@ -3752,10 +3967,10 @@ function registerTreeCommand(program2) {
       let roots;
       let showProjectName;
       if (options.root?.trim()) {
-        const path19 = options.root.trim().replace(/\/$/, "");
-        const node = graph.nodes.get(path19);
+        const path20 = options.root.trim().replace(/\/$/, "");
+        const node = graph.nodes.get(path20);
         if (!node) {
-          process.stderr.write(`Error: path '${path19}' not found
+          process.stderr.write(`Error: path '${path20}' not found
 `);
           process.exit(1);
         }
@@ -3799,7 +4014,7 @@ function printNode(node, prefix, isLast, depth, maxDepth) {
 }
 
 // src/cli/owner.ts
-import path16 from "path";
+import path17 from "path";
 import { access as access3 } from "fs/promises";
 function normalizeForMatch(inputPath) {
   return inputPath.replace(/\\/g, "/").replace(/\/+$/, "");
@@ -3829,11 +4044,11 @@ function registerOwnerCommand(program2) {
       const graph = await loadGraph(cwd);
       const repoRoot = projectRootFromGraph(graph.rootPath);
       const rawPath = options.file.trim();
-      const absolute = path16.resolve(cwd, rawPath);
-      const repoRelative = path16.relative(repoRoot, absolute).split(path16.sep).join("/");
+      const absolute = path17.resolve(cwd, rawPath);
+      const repoRelative = path17.relative(repoRoot, absolute).split(path17.sep).join("/");
       const result = findOwner(graph, repoRoot, repoRelative);
       if (!result.nodePath) {
-        const absPath = path16.resolve(repoRoot, result.file);
+        const absPath = path17.resolve(repoRoot, result.file);
         let exists = true;
         try {
           await access3(absPath);
@@ -3867,7 +4082,7 @@ function registerOwnerCommand(program2) {
 
 // src/core/dependency-resolver.ts
 import { execSync } from "child_process";
-import path17 from "path";
+import path18 from "path";
 var STRUCTURAL_RELATION_TYPES3 = /* @__PURE__ */ new Set(["uses", "calls", "extends", "implements"]);
 var EVENT_RELATION_TYPES2 = /* @__PURE__ */ new Set(["emits", "listens"]);
 function filterRelationType(relType, filter) {
@@ -3944,7 +4159,7 @@ function registerDepsCommand(program2) {
 // src/core/graph-from-git.ts
 import { mkdtemp, rm as rm3 } from "fs/promises";
 import { tmpdir } from "os";
-import path18 from "path";
+import path19 from "path";
 import { execSync as execSync2 } from "child_process";
 async function loadGraphFromRef(projectRoot, ref = "HEAD") {
   const yggPath = ".yggdrasil";
@@ -3955,8 +4170,8 @@ async function loadGraphFromRef(projectRoot, ref = "HEAD") {
     return null;
   }
   try {
-    tmpDir = await mkdtemp(path18.join(tmpdir(), "ygg-git-"));
-    const archivePath = path18.join(tmpDir, "archive.tar");
+    tmpDir = await mkdtemp(path19.join(tmpdir(), "ygg-git-"));
+    const archivePath = path19.join(tmpDir, "archive.tar");
     execSync2(`git archive ${ref} ${yggPath} -o "${archivePath}"`, {
       cwd: projectRoot,
       stdio: "pipe"
@@ -4026,14 +4241,14 @@ function buildTransitiveChains(targetNode, direct, allDependents, reverse) {
   }
   const chains = [];
   for (const node of transitiveOnly) {
-    const path19 = [];
+    const path20 = [];
     let current = node;
     while (current) {
-      path19.unshift(current);
+      path20.unshift(current);
       current = parent.get(current);
     }
-    if (path19.length >= 3) {
-      chains.push(path19.slice(1).map((p) => `<- ${p}`).join(" "));
+    if (path20.length >= 3) {
+      chains.push(path20.slice(1).map((p) => `<- ${p}`).join(" "));
     }
   }
   return chains.sort();
@@ -4050,6 +4265,51 @@ function collectDescendants(graph, nodePath) {
   }
   return result.sort();
 }
+function collectIndirectDependents(graph, directlyAffected) {
+  const directSet = new Set(directlyAffected);
+  const reverse = /* @__PURE__ */ new Map();
+  for (const [nodePath, node] of graph.nodes) {
+    for (const rel of node.meta.relations ?? []) {
+      if (!STRUCTURAL_TYPES.has(rel.type) && rel.type !== "emits" && rel.type !== "listens") continue;
+      const deps = reverse.get(rel.target) ?? /* @__PURE__ */ new Set();
+      deps.add(nodePath);
+      reverse.set(rel.target, deps);
+    }
+  }
+  const bestChain = /* @__PURE__ */ new Map();
+  for (const affected of directlyAffected) {
+    const parent = /* @__PURE__ */ new Map();
+    const queue = [affected];
+    const visited = /* @__PURE__ */ new Set([affected]);
+    while (queue.length > 0) {
+      const current = queue.shift();
+      for (const next of reverse.get(current) ?? []) {
+        if (visited.has(next)) continue;
+        visited.add(next);
+        parent.set(next, current);
+        queue.push(next);
+      }
+    }
+    for (const [node] of parent) {
+      if (directSet.has(node)) continue;
+      const path20 = [node];
+      let current = node;
+      while (parent.has(current)) {
+        current = parent.get(current);
+        path20.push(current);
+      }
+      const chain = path20.map((p) => `<- ${p}`).join(" ");
+      const depth = path20.length;
+      const existing = bestChain.get(node);
+      if (!existing || depth < existing.depth) {
+        bestChain.set(node, { chain, depth });
+      }
+    }
+  }
+  const indirectPaths = [...bestChain.keys()].sort();
+  const chains = indirectPaths.map((p) => bestChain.get(p).chain);
+  return { indirectPaths, chains };
+}
 async function runSimulation(graph, nodePaths, targetNodePath) {
   const budget = graph.config.quality?.context_budget ?? { warning: 1e4, error: 2e4 };
   process.stdout.write("\nChanges in context packages:\n\n");
@@ -4129,19 +4389,32 @@ async function handleAspectImpact(graph, aspectId, simulate) {
     }
   }
   affected.sort((a, b) => a.path.localeCompare(b.path));
+  const { indirectPaths, chains } = collectIndirectDependents(
+    graph,
+    affected.map((a) => a.path)
+  );
   const propagatingFlows = graph.flows.filter((f) => (f.aspects ?? []).includes(aspectId)).map((f) => f.name);
   const impliedBy = graph.aspects.filter((a) => (a.implies ?? []).includes(aspectId)).map((a) => a.id);
   const implies = aspect.implies ?? [];
   process.stdout.write(`Impact of changes in aspect ${aspectId}:
 
 `);
-  process.stdout.write(`Affected nodes (${affected.length}):
+  process.stdout.write(`Directly affected (${affected.length}):
 `);
   if (affected.length === 0) {
     process.stdout.write("  (none)\n");
   } else {
     for (const { path: p, source } of affected) {
       process.stdout.write(`  ${p} (${source})
+`);
+    }
+  }
+  if (chains.length > 0) {
+    process.stdout.write(`
+Indirectly affected (structural dependents):
+`);
+    for (let i = 0; i < indirectPaths.length; i++) {
+      process.stdout.write(`  ${indirectPaths[i]}  ${chains[i]}
 `);
     }
   }
@@ -4155,12 +4428,13 @@ Flows propagating this aspect: ${propagatingFlows.length > 0 ? propagatingFlows.
   process.stdout.write(`Implies: ${implies.length > 0 ? implies.join(", ") : "(none)"}
 `);
   process.stdout.write(`
-Total scope: ${affected.length} nodes, ${propagatingFlows.length} flows
+Total scope: ${affected.length + indirectPaths.length} nodes, ${propagatingFlows.length} flows
 `);
-  if (simulate && affected.length > 0) {
+  const combinedPaths = [...affected.map((a) => a.path), ...indirectPaths];
+  if (simulate && combinedPaths.length > 0) {
     await runSimulation(
       graph,
-      affected.map((a) => a.path),
+      combinedPaths,
       null
     );
   }
@@ -4183,6 +4457,7 @@ async function handleFlowImpact(graph, flowName, simulate) {
   }
   const sorted = [...participants].sort();
   const flowAspects = flow.aspects ?? [];
+  const { indirectPaths, chains } = collectIndirectDependents(graph, sorted);
   process.stdout.write(`Impact of changes in flow ${flow.name}:
 
 `);
@@ -4194,6 +4469,15 @@ async function handleFlowImpact(graph, flowName, simulate) {
       const isDeclared = flow.nodes.includes(p);
       const suffix = isDeclared ? "" : " (descendant)";
       process.stdout.write(`  ${p}${suffix}
+`);
+    }
+  }
+  if (chains.length > 0) {
+    process.stdout.write(`
+Indirectly affected (structural dependents):
+`);
+    for (let i = 0; i < indirectPaths.length; i++) {
+      process.stdout.write(`  ${indirectPaths[i]}  ${chains[i]}
 `);
     }
   }
@@ -4203,10 +4487,11 @@ Flow aspects: ${flowAspects.length > 0 ? flowAspects.join(", ") : "(none)"}
 `
   );
   process.stdout.write(`
-Total scope: ${sorted.length} nodes
+Total scope: ${sorted.length + indirectPaths.length} nodes
 `);
-  if (simulate && sorted.length > 0) {
-    await runSimulation(graph, sorted, null);
+  const combinedPaths = [...sorted, ...indirectPaths];
+  if (simulate && combinedPaths.length > 0) {
+    await runSimulation(graph, combinedPaths, null);
   }
 }
 function registerImpactCommand(program2) {
@@ -4343,6 +4628,27 @@ function registerImpactCommand(program2) {
 `);
           }
         }
+        const alreadyShown = /* @__PURE__ */ new Set([nodePath, ...filteredAllDependents, ...descendants, ...eventDependents.map((e) => e.path)]);
+        let descIndirectPaths = [];
+        if (descendants.length > 0) {
+          const { indirectPaths: rawIndirect, chains: rawChains } = collectIndirectDependents(graph, descendants);
+          const filteredIndirect = [];
+          const filteredChains = [];
+          for (let i = 0; i < rawIndirect.length; i++) {
+            if (!alreadyShown.has(rawIndirect[i])) {
+              filteredIndirect.push(rawIndirect[i]);
+              filteredChains.push(rawChains[i]);
+            }
+          }
+          descIndirectPaths = filteredIndirect;
+          if (filteredIndirect.length > 0) {
+            process.stdout.write("\nIndirectly affected (structural dependents of descendants):\n");
+            for (let i = 0; i < filteredIndirect.length; i++) {
+              process.stdout.write(`  ${filteredIndirect[i]}  ${filteredChains[i]}
+`);
+            }
+          }
+        }
         process.stdout.write(
           `
 Flows: ${flows.length > 0 ? flows.join(", ") : "(none)"}
@@ -4372,7 +4678,7 @@ Flows: ${flows.length > 0 ? flows.join(", ") : "(none)"}
 `);
           }
         }
-        const allAffected = /* @__PURE__ */ new Set([...filteredAllDependents, ...descendants, ...eventDependents.map((e) => e.path)]);
+        const allAffected = /* @__PURE__ */ new Set([...filteredAllDependents, ...descendants, ...eventDependents.map((e) => e.path), ...descIndirectPaths]);
         process.stdout.write(
           `
 Total scope: ${allAffected.size} nodes, ${flows.length} flows, ${aspectsInScope.length} aspects