@chrisdudek/yg 2.5.0 → 2.7.0

package/dist/bin.js

@@ -80,7 +80,8 @@ BEFORE reading, researching, planning, OR modifying ANY mapped file:
      - Assessing what is affected by a change \u2192 yg impact --node <owner>
      - Planning modifications \u2192 both (build-context first, then impact)
   \`yg build-context --node <path>\`. Read the YAML map for topology,
-  then read artifact files listed in the artifacts section. For quick
+  starting with the glossary at the top (aspect and flow definitions),
+  then read artifact files listed inline on each element. 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.
@@ -148,6 +149,7 @@ What matters is the ACTION you are performing, not what instructed it. If the ac
 | "I'm only grepping for references" | Grep finds text; yg impact finds structural dependencies. Use both. |
 | "I'll use the graph later when I modify" | Graph-first means BEFORE reading, not before modifying |
 | "I'll grep the codebase to find where to start" | Run \`yg select --task\` first \u2014 it matches your intent against graph artifacts. Then \`yg owner\` on results. |
+| "Drift is blocking repo-check, let me just sync it" | Drift means artifacts are stale. Update artifacts first, then sync. \`drift-sync\` without artifact update = hiding staleness. |
 
 ### Failure States
 
@@ -210,9 +212,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>. 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.
+         for topology, starting with the glossary at the top for aspect and
+         flow definitions, then read artifact files listed inline on each
+         element. 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.
@@ -239,7 +242,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 (after each file, not batched \u2014 context is freshest immediately after the change)
+- [ ] 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). If the node's purpose changed, update \`description\` in \`yg-node.yaml\`.
 - [ ] 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
 
@@ -257,7 +260,7 @@ You are not allowed to edit or create source code without establishing graph cov
 
 1. Create aspects first (cross-cutting requirements the new code must satisfy)
 2. Create flows if the code participates in a business process
-3. Create nodes with full artifacts \u2014 responsibility, interface, internals
+3. Create nodes with full artifacts \u2014 description in \`yg-node.yaml\`, responsibility, interface, internals
 4. Review the context package (\`yg build-context\`) \u2014 it is now the behavioral specification
 5. Implement code that satisfies the specification
 6. The graph specifies WHAT and WHY; the code implements HOW (framework APIs, library choices)
@@ -282,6 +285,7 @@ Per area checklist:
 - [ ] 1. \`yg owner --file <path>\` \u2014 confirm no coverage
 - [ ] 2. Determine node granularity \u2014 propose to user if unclear
 - [ ] 3. Create node directory, read \`schemas/yg-node.yaml\`, create \`yg-node.yaml\`
+- [ ] 3b. Write \`description\` in \`yg-node.yaml\` \u2014 a short summary of what the node does
 - [ ] 4. Analyze source \u2014 for each artifact type in \`yg-config.yaml artifacts\`: extract content, do not invent
 - [ ] 5. Identify relations \u2014 add to \`yg-node.yaml\`
 - [ ] 6. Identify cross-cutting requirements \u2014 add matching aspects, create if needed
@@ -352,7 +356,7 @@ When reviewing graph quality (triggered by user or quality improvement):
 - **Budget warning (W005/W006)** \u2192 informational. \`yg validate\` shows a breakdown (own/hierarchy/aspects/flows/dependencies). Large inherited context means the system is complex \u2014 this is not a problem to fix, it is reality to acknowledge. Do not delete knowledge from artifacts. Do not attempt to "reduce" inherited context.
 - **Own budget warning (W015)** \u2192 own artifacts are large. Consider splitting this node's responsibilities into child nodes. Redistribute knowledge across children so total knowledge is preserved or increased, never reduced.
 - **Corrupted \`.yggdrasil/\` files** \u2192 report to user. Do not attempt repair.
-- **Incremental sync** \u2192 run \`yg drift-sync\` every 3-5 source files during multi-file tasks. Do not defer to end.`;
+- **Incremental sync** \u2192 run \`yg drift-sync\` every 3-5 source files during multi-file tasks. Do not defer to end. But NEVER run \`yg drift-sync\` to silence a failing drift check \u2014 drift is a signal that artifacts need updating. First update artifacts, then sync.`;
 var KNOWLEDGE_BASE = `## KNOWLEDGE BASE
 
 ### Graph Structure
@@ -389,9 +393,20 @@ Projects can define additional artifact types in \`yg-config.yaml\` under \`arti
 
 ### Context Assembly
 
-**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>\`.
+**Reading context:** \`yg build-context --node <path>\` returns a YAML map structured as follows:
 
-**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.
+- **\`glossary\`** (top) \u2014 definitions for every aspect and flow referenced in the map, each with \`files\` listing their artifact paths. Read this first to understand IDs used throughout.
+- **\`node\`** \u2014 the target node with inline \`files\` (its artifact paths). No \`yg-node.yaml\` in file lists.
+- **\`hierarchy\`** \u2014 ancestor and sibling nodes, each with inline \`files\`.
+- **\`dependencies\`** \u2014 dependency nodes, each with inline \`files\`.
+- **\`meta\`** (bottom) \u2014 context assembly metadata.
+- YAML comments before each section guide reading order.
+
+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 \u2014 start with the \`glossary\` to understand aspects and flows, then the \`node\` section for the target. Read artifact files inline on each element 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.
+
+The glossary at the top defines all aspects and flows \u2014 read it first to understand IDs used throughout.
 
 **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.
 
@@ -440,7 +455,7 @@ When code anchors (\`anchors\` in an aspect entry in \`yg-node.yaml\`) are prese
 
 - [ ] 1. Read \`schemas/yg-flow.yaml\`
 - [ ] 2. Create \`flows/<name>/\` directory
-- [ ] 3. Write \`yg-flow.yaml\` \u2014 declare participants and flow-level aspects
+- [ ] 3. Write \`yg-flow.yaml\` \u2014 name, description, nodes (participant list), and flow-level aspects
 - [ ] 4. Write \`description.md\` with required sections: Business context, Trigger, Goal, Participants, Paths (at least Happy path), Invariants across all paths
 - [ ] 5. \`yg validate\`
 
@@ -453,7 +468,8 @@ Test: "Does this describe what happens in the world, or only in the software?" I
 - **English only** for all files in \`.yggdrasil/\`. Conversation can be any language.
 - **Read schemas before creating** any \`yg-node.yaml\`, \`yg-aspect.yaml\`, or \`yg-flow.yaml\`.
 - **Tools read, you write.** The \`yg\` CLI only reads, validates, and manages metadata. You create and edit files manually.
-- **Incremental sync.** Run \`yg drift-sync\` after every 3-5 source file changes. Do not defer to end of task.
+- **Incremental sync.** Run \`yg drift-sync\` after every 3-5 source file changes. Do not defer to end of task. \`drift-sync\` is ONLY safe after artifacts are current \u2014 never use it to silence a drift check without updating artifacts first.
+- **Description maintenance.** Every \`yg-node.yaml\`, \`yg-aspect.yaml\`, and \`yg-flow.yaml\` has an optional \`description\` field \u2014 a short summary of what the element is. Write it when creating new elements. Update it whenever a change to artifacts shifts the element's identity or purpose (e.g., responsibility split, scope change). Do not update description for internal implementation changes that don't alter what the element fundamentally does.
 - **Completeness test:** Two checks, both required:
   1. **Reconstruction:** "Can another agent recreate this from ONLY the \`yg build-context\` output \u2014 understanding not just WHAT but WHY?" Test: rejected alternatives, correct algorithm, design arguments.
   2. **Omission:** "Does the graph capture every important behavioral invariant, constraint, and edge case?" Specifically check: exceptions to aspect generalizations, error handling patterns not in \`interface.md\`, concurrency behaviors not in \`internals.md\`.
@@ -493,7 +509,7 @@ yg drift-sync --node <path> [--recursive] | --all
 | Information specific to this node | Local node artifact (check \`yg-config.yaml artifacts\` for types) |
 | Rule that applies to many nodes | Aspect (content \`.md\` files in \`aspects/<id>/\`) |
 | Architectural invariant for a node type | Required aspect in \`yg-config.yaml node_types\` |
-| Business process participation | Flow (\`yg-flow.yaml participants\`) |
+| Business process participation | Flow (\`yg-flow.yaml nodes\`) |
 | Process-level requirement | Flow \`aspects\` + aspect directory |
 | Context shared across a domain | Parent node artifact |
 | Technology stack | Node artifact at appropriate hierarchy level |
@@ -1172,10 +1188,6 @@ 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";
@@ -1298,12 +1310,14 @@ async function parseNodeYaml(filePath) {
   if (!raw.type || typeof raw.type !== "string" || raw.type.trim() === "") {
     throw new Error(`yg-node.yaml at ${filePath}: missing or empty 'type'`);
   }
+  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);
   return {
     name: raw.name.trim(),
     type: raw.type.trim(),
+    description,
     aspects,
     blackbox: raw.blackbox ?? false,
     relations: relations.length > 0 ? relations : void 0,
@@ -1509,13 +1523,18 @@ async function parseFlow(flowDir, flowYamlPath) {
   if (!raw.name || typeof raw.name !== "string" || raw.name.trim() === "") {
     throw new Error(`yg-flow.yaml at ${flowYamlPath}: missing or empty 'name'`);
   }
-  const nodes = raw.nodes;
+  const description = typeof raw.description === "string" ? raw.description.trim() : void 0;
+  const nodes = raw.nodes ?? raw.participants;
   if (!Array.isArray(nodes) || nodes.length === 0) {
-    throw new Error(`yg-flow.yaml at ${flowYamlPath}: 'nodes' must be a non-empty array`);
+    throw new Error(
+      `yg-flow.yaml at ${flowYamlPath}: 'nodes' (or 'participants') must be a non-empty array`
+    );
   }
   const nodePaths = nodes.filter((n) => typeof n === "string");
   if (nodePaths.length === 0) {
-    throw new Error(`yg-flow.yaml at ${flowYamlPath}: 'nodes' must contain string node paths`);
+    throw new Error(
+      `yg-flow.yaml at ${flowYamlPath}: 'nodes' (or 'participants') must contain string node paths`
+    );
   }
   let aspects;
   if (raw.aspects !== void 0) {
@@ -1529,6 +1548,7 @@ async function parseFlow(flowDir, flowYamlPath) {
   return {
     path: path6.basename(flowDir),
     name: raw.name.trim(),
+    description,
     nodes: nodePaths,
     ...aspects !== void 0 && { aspects },
     artifacts
@@ -1732,19 +1752,20 @@ async function scanAspectsDirectory(dirPath, aspectsRoot, aspects) {
   }
 }
 async function loadFlows(flowsDir) {
+  let entries;
   try {
-    const entries = await readdir4(flowsDir, { withFileTypes: true });
-    const flows = [];
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      const flowYamlPath = path9.join(flowsDir, entry.name, "yg-flow.yaml");
-      const flow = await parseFlow(path9.join(flowsDir, entry.name), flowYamlPath);
-      flows.push(flow);
-    }
-    return flows;
+    entries = await readdir4(flowsDir, { withFileTypes: true });
   } catch {
     return [];
   }
+  const flows = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const flowYamlPath = path9.join(flowsDir, entry.name, "yg-flow.yaml");
+    const flow = await parseFlow(path9.join(flowsDir, entry.name), flowYamlPath);
+    flows.push(flow);
+  }
+  return flows;
 }
 async function loadSchemas(schemasDir) {
   try {
@@ -1774,6 +1795,7 @@ function estimateTokens(text) {
 // src/core/context-builder.ts
 var STRUCTURAL_RELATION_TYPES = /* @__PURE__ */ new Set(["uses", "calls", "extends", "implements"]);
 var EVENT_RELATION_TYPES = /* @__PURE__ */ new Set(["emits", "listens"]);
+var YG_YAML_FILES = /* @__PURE__ */ new Set(["yg-node.yaml", "yg-aspect.yaml", "yg-flow.yaml"]);
 async function buildContext(graph, nodePath) {
   const node = graph.nodes.get(nodePath);
   if (!node) {
@@ -2132,7 +2154,7 @@ function toContextMapOutput(pkg2, graph) {
   });
   const participatingFlows = collectParticipatingFlows(graph, node);
   const flowRefs = participatingFlows.map((f) => {
-    const ref = { path: f.path, name: f.name };
+    const ref = { path: f.path };
     if (f.aspects?.length) ref.aspects = f.aspects;
     return ref;
   });
@@ -2140,7 +2162,7 @@ function toContextMapOutput(pkg2, graph) {
   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 };
+    return { path: a.path, name: a.meta.name, type: a.meta.type, description: a.meta.description, aspects: expanded, files: buildNodeFiles(a, config, `model/${a.path}`) };
   });
   const ancestorPaths = new Set(ancestors.map((a) => a.path));
   const depRefs = [];
@@ -2152,23 +2174,26 @@ function toContextMapOutput(pkg2, graph) {
     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 ancestorNode = graph.nodes.get(a.path);
+      return { path: a.path, name: a.meta.name, type: a.meta.type, description: a.meta.description, aspects: expanded, files: ancestorNode ? buildDepNodeFiles(ancestorNode, config, `model/${a.path}`) : [] };
     });
     const depEffectiveAspects = [...collectEffectiveAspectIds(graph, target.path)];
     const ref = {
       path: target.path,
       name: target.meta.name,
       type: target.meta.type,
+      description: target.meta.description,
       relation: relation.type,
       aspects: depEffectiveAspects,
-      hierarchy: depHierarchy
+      hierarchy: depHierarchy,
+      files: buildDepNodeFiles(target, config, `model/${target.path}`)
     };
     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 glossary = buildGlossary(node, depRefs, graph);
   const breakdown = computeBudgetBreakdown(pkg2, graph);
   const warningThreshold = config.quality?.context_budget?.warning ?? 1e4;
   const errorThreshold = config.quality?.context_budget?.error ?? 2e4;
@@ -2180,56 +2205,29 @@ function toContextMapOutput(pkg2, graph) {
       path: pkg2.nodePath,
       name: pkg2.nodeName,
       type: node.meta.type,
+      description: node.meta.description,
       mappings: normalizeMappingPaths(node.meta.mapping),
       aspects: nodeAspects,
-      flows: flowRefs
+      flows: flowRefs,
+      files: buildNodeFiles(node, config, `model/${pkg2.nodePath}`)
     },
     hierarchy: hierarchyRefs,
     dependencies: depRefs,
-    artifacts: registry
+    glossary
   };
 }
-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 = {};
+function buildNodeFiles(node, config, prefix) {
+  const configKeys = Object.keys(config.artifacts ?? {});
+  return configKeys.filter((f) => !YG_YAML_FILES.has(f) && node.artifacts.some((a) => a.filename === f)).map((f) => `${prefix}/${f}`);
+}
+function buildDepNodeFiles(node, config, prefix) {
+  const structural = Object.entries(config.artifacts ?? {}).filter(([, c]) => c.included_in_relations).map(([f]) => f);
+  const filenames = structural.length > 0 ? structural : Object.keys(config.artifacts ?? {});
+  return filenames.filter((f) => !YG_YAML_FILES.has(f) && node.artifacts.some((a) => a.filename === f)).map((f) => `${prefix}/${f}`);
+}
+function buildGlossary(node, dependencies, graph) {
   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) {
@@ -2238,33 +2236,29 @@ function buildArtifactRegistry(node, ancestors, dependencies, graph) {
   }
   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 files = aspect.artifacts.filter((a) => !YG_YAML_FILES.has(a.filename)).map((a) => `aspects/${aspect.id}/${a.filename}`);
     const entry = {
       name: aspect.name,
       files
     };
+    if (aspect.description) entry.description = aspect.description;
+    if (aspect.stability) entry.stability = aspect.stability;
     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 files = flow.artifacts.filter((a) => !YG_YAML_FILES.has(a.filename)).map((a) => `flows/${flow.path}/${a.filename}`);
     const entry = {
       name: flow.name,
+      participants: flow.nodes,
       files
     };
+    if (flow.description) entry.description = flow.description;
     if (flow.aspects?.length) entry.aspects = flow.aspects;
     flows[flow.path] = entry;
   }
-  return { nodes, aspects, flows };
+  return { aspects, flows };
 }
 function collectEffectiveAspectIds(graph, nodePath) {
   const node = graph.nodes.get(nodePath);
@@ -2285,23 +2279,39 @@ function collectEffectiveAspectIds(graph, nodePath) {
 }
 
 // src/formatters/context-text.ts
-import { stringify } from "yaml";
+import { Document } 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
+  const output = {};
+  output.project = data.project;
+  output.glossary = data.glossary;
+  output.node = data.node;
+  if (data.hierarchy.length > 0) output.hierarchy = data.hierarchy;
+  if (data.dependencies.length > 0) output.dependencies = data.dependencies;
+  output.meta = {
+    "token-count": data.meta.tokenCount,
+    "budget-status": data.meta.budgetStatus,
+    breakdown: data.meta.breakdown
   };
-  for (const key of Object.keys(output)) {
-    if (output[key] === void 0) delete output[key];
+  const doc = new Document(output, { aliasDuplicateObjects: false });
+  const map = doc.contents;
+  for (const pair of map.items) {
+    const key = String(pair.key);
+    switch (key) {
+      case "glossary":
+        pair.key.commentBefore = " Glossary: definitions of all aspects and flows referenced in this context.\n Read this first \u2014 IDs below (in node, hierarchy, dependencies) refer to entries here.";
+        break;
+      case "node":
+        pair.key.commentBefore = " Target node: the component you are working on.";
+        break;
+      case "hierarchy":
+        pair.key.commentBefore = " Hierarchy: ancestor modules from root to parent. Context is inherited top-down.";
+        break;
+      case "dependencies":
+        pair.key.commentBefore = " Dependencies: components this node directly depends on.";
+        break;
+    }
   }
-  return stringify(output, { lineWidth: 0 });
+  return doc.toString({ lineWidth: 0 });
 }
 function formatFullContent(files) {
   if (files.length === 0) return "";
@@ -2355,6 +2365,7 @@ async function validate(graph, scope = "all") {
     issues.push(...checkInvalidArtifactConditions(graph));
     issues.push(...await checkContextBudget(graph));
     issues.push(...checkHighFanOut(graph));
+    issues.push(...checkMissingDescriptions(graph));
   }
   issues.push(...checkSchemas(graph));
   issues.push(...checkRelationTargets(graph));
@@ -3087,6 +3098,41 @@ function pct(value, total) {
   if (total === 0) return "0%";
   return `${Math.round(value / total * 100)}%`;
 }
+function checkMissingDescriptions(graph) {
+  const issues = [];
+  for (const [nodePath, node] of graph.nodes) {
+    if (!node.meta.description?.trim()) {
+      issues.push({
+        severity: "warning",
+        code: "W016",
+        rule: "missing-description",
+        message: `Node has no description`,
+        nodePath
+      });
+    }
+  }
+  for (const aspect of graph.aspects) {
+    if (!aspect.description?.trim()) {
+      issues.push({
+        severity: "warning",
+        code: "W016",
+        rule: "missing-description",
+        message: `Aspect '${aspect.id}' has no description`
+      });
+    }
+  }
+  for (const flow of graph.flows) {
+    if (!flow.description?.trim()) {
+      issues.push({
+        severity: "warning",
+        code: "W016",
+        rule: "missing-description",
+        message: `Flow '${flow.name}' has no description`
+      });
+    }
+  }
+  return issues;
+}
 
 // src/cli/build-context.ts
 function collectRelevantNodePaths(graph, nodePath) {
@@ -3139,22 +3185,31 @@ function registerBuildCommand(program2) {
       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 });
-            }
+        const allFiles = [];
+        async function collectFile(filePath) {
+          if (seen.has(filePath)) return;
+          seen.add(filePath);
+          const content = await findFileContent(filePath, graph);
+          if (content !== void 0) {
+            allFiles.push({ path: filePath, content });
+          }
+        }
+        for (const aspect of Object.values(mapOutput.glossary.aspects)) {
+          for (const f of aspect.files) await collectFile(f);
+        }
+        for (const flow of Object.values(mapOutput.glossary.flows)) {
+          for (const f of flow.files) await collectFile(f);
+        }
+        for (const f of mapOutput.node.files) await collectFile(f);
+        for (const ancestor of mapOutput.hierarchy) {
+          for (const f of ancestor.files ?? []) await collectFile(f);
+        }
+        for (const dep of mapOutput.dependencies) {
+          for (const ancestor of dep.hierarchy) {
+            for (const f of ancestor.files ?? []) await collectFile(f);
           }
+          for (const f of dep.files ?? []) await collectFile(f);
         }
         output += formatFullContent(allFiles);
       }
@@ -3167,14 +3222,6 @@ 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("/");
@@ -3182,9 +3229,6 @@ async function findFileContent(filePath, graph) {
     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;
   }
@@ -3195,9 +3239,6 @@ async function findFileContent(filePath, graph) {
     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;
   }
@@ -3208,9 +3249,6 @@ async function findFileContent(filePath, graph) {
     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;
   }
@@ -3266,12 +3304,12 @@ ${errors.length} errors, ${warnings.length} warnings.
 import chalk2 from "chalk";
 
 // src/io/drift-state-store.ts
-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 { 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 { parse as yamlParse } from "yaml";
 var DRIFT_STATE_DIR = ".drift-state";
 function nodeStatePath(yggRoot, nodePath) {
-  return path13.join(yggRoot, DRIFT_STATE_DIR, `${nodePath}.json`);
+  return path12.join(yggRoot, DRIFT_STATE_DIR, `${nodePath}.json`);
 }
 async function scanJsonFiles(dir, baseDir) {
   const results = [];
@@ -3282,12 +3320,12 @@ async function scanJsonFiles(dir, baseDir) {
     return results;
   }
   for (const entry of entries) {
-    const fullPath = path13.join(dir, entry.name);
+    const fullPath = path12.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 = path13.relative(baseDir, fullPath);
+      const relPath = path12.relative(baseDir, fullPath);
       const nodePath = relPath.replace(/\\/g, "/").replace(/\.json$/, "");
       results.push(nodePath);
     }
@@ -3295,13 +3333,13 @@ async function scanJsonFiles(dir, baseDir) {
   return results;
 }
 async function removeEmptyParents(filePath, stopDir) {
-  let dir = path13.dirname(filePath);
+  let dir = path12.dirname(filePath);
   while (dir !== stopDir && dir.startsWith(stopDir)) {
     try {
       const entries = await readdir6(dir);
       if (entries.length === 0) {
         await rm2(dir, { recursive: true });
-        dir = path13.dirname(dir);
+        dir = path12.dirname(dir);
       } else {
         break;
       }
@@ -3313,7 +3351,7 @@ async function removeEmptyParents(filePath, stopDir) {
 async function readNodeDriftState(yggRoot, nodePath) {
   try {
     const filePath = nodeStatePath(yggRoot, nodePath);
-    const content = await readFile15(filePath, "utf-8");
+    const content = await readFile14(filePath, "utf-8");
     const parsed = JSON.parse(content);
     return parsed;
   } catch {
@@ -3322,12 +3360,12 @@ async function readNodeDriftState(yggRoot, nodePath) {
 }
 async function writeNodeDriftState(yggRoot, nodePath, nodeState) {
   const filePath = nodeStatePath(yggRoot, nodePath);
-  await mkdir3(path13.dirname(filePath), { recursive: true });
+  await mkdir3(path12.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 = path13.join(yggRoot, DRIFT_STATE_DIR);
+  const driftDir = path12.join(yggRoot, DRIFT_STATE_DIR);
   const allNodePaths = await scanJsonFiles(driftDir, driftDir);
   const removed = [];
   for (const nodePath of allNodePaths) {
@@ -3341,7 +3379,7 @@ async function garbageCollectDriftState(yggRoot, validNodePaths) {
   return removed.sort();
 }
 async function readDriftState(yggRoot) {
-  const driftPath = path13.join(yggRoot, DRIFT_STATE_DIR);
+  const driftPath = path12.join(yggRoot, DRIFT_STATE_DIR);
   let driftStat;
   try {
     driftStat = await stat5(driftPath);
@@ -3349,7 +3387,7 @@ async function readDriftState(yggRoot) {
     return {};
   }
   if (driftStat.isFile()) {
-    const content = await readFile15(driftPath, "utf-8");
+    const content = await readFile14(driftPath, "utf-8");
     let raw;
     try {
       raw = JSON.parse(content);
@@ -3381,20 +3419,20 @@ async function readDriftState(yggRoot) {
 }
 
 // src/utils/hash.ts
-import { readFile as readFile16, readdir as readdir7, stat as stat6 } from "fs/promises";
-import path14 from "path";
+import { readFile as readFile15, readdir as readdir7, stat as stat6 } from "fs/promises";
+import path13 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 readFile16(filePath);
+  const content = await readFile15(filePath);
   return createHash("sha256").update(content).digest("hex");
 }
 async function loadRootGitignoreStack(projectRoot) {
   if (!projectRoot) return [];
   try {
-    const content = await readFile16(path14.join(projectRoot, ".gitignore"), "utf-8");
+    const content = await readFile15(path13.join(projectRoot, ".gitignore"), "utf-8");
     const matcher = ignoreFactory();
     matcher.add(content);
     return [{ basePath: projectRoot, matcher }];
@@ -3404,7 +3442,7 @@ async function loadRootGitignoreStack(projectRoot) {
 }
 function isIgnoredByStack(candidatePath, stack) {
   for (const { basePath, matcher } of stack) {
-    const relativePath = path14.relative(basePath, candidatePath);
+    const relativePath = path13.relative(basePath, candidatePath);
     if (relativePath === "" || relativePath.startsWith("..")) continue;
     if (matcher.ignores(relativePath) || matcher.ignores(relativePath + "/")) return true;
   }
@@ -3419,7 +3457,7 @@ async function hashTrackedFiles(projectRoot, trackedFiles, storedFileData, exclu
   const gitignoreStack = await loadRootGitignoreStack(projectRoot);
   const allFiles = [];
   for (const tf of trackedFiles) {
-    const absPath = path14.join(projectRoot, tf.path);
+    const absPath = path13.join(projectRoot, tf.path);
     try {
       const st = await stat6(absPath);
       if (st.isDirectory()) {
@@ -3429,7 +3467,7 @@ async function hashTrackedFiles(projectRoot, trackedFiles, storedFileData, exclu
         });
         for (const entry of dirEntries) {
           allFiles.push({
-            relPath: path14.join(tf.path, entry.relPath).replace(/\\/g, "/"),
+            relPath: path13.join(tf.path, entry.relPath).replace(/\\/g, "/"),
             absPath: entry.absPath,
             mtimeMs: entry.mtimeMs
           });
@@ -3469,7 +3507,7 @@ async function hashTrackedFiles(projectRoot, trackedFiles, storedFileData, exclu
 async function collectDirectoryFilePaths(directoryPath, rootDirectoryPath, options) {
   let stack = options.gitignoreStack ?? [];
   try {
-    const localContent = await readFile16(path14.join(directoryPath, ".gitignore"), "utf-8");
+    const localContent = await readFile15(path13.join(directoryPath, ".gitignore"), "utf-8");
     const localMatcher = ignoreFactory();
     localMatcher.add(localContent);
     stack = [...stack, { basePath: directoryPath, matcher: localMatcher }];
@@ -3479,7 +3517,7 @@ async function collectDirectoryFilePaths(directoryPath, rootDirectoryPath, optio
   const dirs = [];
   const files = [];
   for (const entry of entries) {
-    const absoluteChildPath = path14.join(directoryPath, entry.name);
+    const absoluteChildPath = path13.join(directoryPath, entry.name);
     if (isIgnoredByStack(absoluteChildPath, stack)) continue;
     if (entry.isDirectory()) dirs.push(absoluteChildPath);
     else if (entry.isFile()) files.push(absoluteChildPath);
@@ -3492,7 +3530,7 @@ async function collectDirectoryFilePaths(directoryPath, rootDirectoryPath, optio
     Promise.all(files.map(async (f) => {
       const fileStat = await stat6(f);
       return {
-        relPath: path14.relative(rootDirectoryPath, f),
+        relPath: path13.relative(rootDirectoryPath, f),
         absPath: f,
         mtimeMs: fileStat.mtimeMs
       };
@@ -3505,14 +3543,14 @@ async function collectDirectoryFilePaths(directoryPath, rootDirectoryPath, optio
 }
 
 // src/core/context-files.ts
-import path15 from "path";
+import path14 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 = path15.dirname(graph.rootPath);
-  const yggPrefix = path15.relative(projectRoot, graph.rootPath);
-  const yggPrefixNormalized = yggPrefix.split(path15.sep).join("/");
+  const projectRoot = path14.dirname(graph.rootPath);
+  const yggPrefix = path14.relative(projectRoot, graph.rootPath);
+  const yggPrefixNormalized = yggPrefix.split(path14.sep).join("/");
   const configArtifactKeys = new Set(Object.keys(graph.config.artifacts ?? {}));
   function addFile(filePath, category) {
     if (seen.has(filePath)) return;
@@ -3625,7 +3663,7 @@ function collectParticipatingFlows2(graph, node, ancestors) {
 
 // src/core/drift-detector.ts
 import { access as access2 } from "fs/promises";
-import path16 from "path";
+import path15 from "path";
 function getChildMappingExclusions(graph, nodePath) {
   const node = graph.nodes.get(nodePath);
   if (!node) return [];
@@ -3647,7 +3685,7 @@ function getChildMappingExclusions(graph, nodePath) {
   return exclusions;
 }
 async function detectDrift(graph, filterNodePath) {
-  const projectRoot = path16.dirname(graph.rootPath);
+  const projectRoot = path15.dirname(graph.rootPath);
   const driftState = await readDriftState(graph.rootPath);
   const entries = [];
   for (const [nodePath, node] of graph.nodes) {
@@ -3729,14 +3767,14 @@ async function detectDrift(graph, filterNodePath) {
   };
 }
 function categorizeFile(filePath, _rootPath, projectRoot) {
-  const yggPrefix = path16.relative(projectRoot, _rootPath);
-  const normalizedPrefix = yggPrefix.split(path16.sep).join("/");
+  const yggPrefix = path15.relative(projectRoot, _rootPath);
+  const normalizedPrefix = yggPrefix.split(path15.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 = path16.join(projectRoot, mp);
+    const absPath = path15.join(projectRoot, mp);
     try {
       await access2(absPath);
       return false;
@@ -3746,7 +3784,7 @@ async function allPathsMissing(projectRoot, mappingPaths) {
   return true;
 }
 async function syncDriftState(graph, nodePath) {
-  const projectRoot = path16.dirname(graph.rootPath);
+  const projectRoot = path15.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}`);
@@ -4066,10 +4104,10 @@ function registerTreeCommand(program2) {
       let roots;
       let showProjectName;
       if (options.root?.trim()) {
-        const path20 = options.root.trim().replace(/\/$/, "");
-        const node = graph.nodes.get(path20);
+        const path19 = options.root.trim().replace(/\/$/, "");
+        const node = graph.nodes.get(path19);
         if (!node) {
-          process.stderr.write(`Error: path '${path20}' not found
+          process.stderr.write(`Error: path '${path19}' not found
 `);
           process.exit(1);
         }
@@ -4113,7 +4151,7 @@ function printNode(node, prefix, isLast, depth, maxDepth) {
 }
 
 // src/cli/owner.ts
-import path17 from "path";
+import path16 from "path";
 import { access as access3 } from "fs/promises";
 function normalizeForMatch(inputPath) {
   return inputPath.replace(/\\/g, "/").replace(/\/+$/, "");
@@ -4143,11 +4181,11 @@ function registerOwnerCommand(program2) {
       const graph = await loadGraph(cwd);
       const repoRoot = projectRootFromGraph(graph.rootPath);
       const rawPath = options.file.trim();
-      const absolute = path17.resolve(cwd, rawPath);
-      const repoRelative = path17.relative(repoRoot, absolute).split(path17.sep).join("/");
+      const absolute = path16.resolve(cwd, rawPath);
+      const repoRelative = path16.relative(repoRoot, absolute).split(path16.sep).join("/");
       const result = findOwner(graph, repoRoot, repoRelative);
       if (!result.nodePath) {
-        const absPath = path17.resolve(repoRoot, result.file);
+        const absPath = path16.resolve(repoRoot, result.file);
         let exists = true;
         try {
           await access3(absPath);
@@ -4181,7 +4219,7 @@ function registerOwnerCommand(program2) {
 
 // src/core/dependency-resolver.ts
 import { execSync } from "child_process";
-import path18 from "path";
+import path17 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) {
@@ -4258,7 +4296,7 @@ function registerDepsCommand(program2) {
 // src/core/graph-from-git.ts
 import { mkdtemp, rm as rm3 } from "fs/promises";
 import { tmpdir } from "os";
-import path19 from "path";
+import path18 from "path";
 import { execSync as execSync2 } from "child_process";
 async function loadGraphFromRef(projectRoot, ref = "HEAD") {
   const yggPath = ".yggdrasil";
@@ -4269,8 +4307,8 @@ async function loadGraphFromRef(projectRoot, ref = "HEAD") {
     return null;
   }
   try {
-    tmpDir = await mkdtemp(path19.join(tmpdir(), "ygg-git-"));
-    const archivePath = path19.join(tmpDir, "archive.tar");
+    tmpDir = await mkdtemp(path18.join(tmpdir(), "ygg-git-"));
+    const archivePath = path18.join(tmpDir, "archive.tar");
     execSync2(`git archive ${ref} ${yggPath} -o "${archivePath}"`, {
       cwd: projectRoot,
       stdio: "pipe"
@@ -4340,14 +4378,14 @@ function buildTransitiveChains(targetNode, direct, allDependents, reverse) {
   }
   const chains = [];
   for (const node of transitiveOnly) {
-    const path20 = [];
+    const path19 = [];
     let current = node;
     while (current) {
-      path20.unshift(current);
+      path19.unshift(current);
       current = parent.get(current);
     }
-    if (path20.length >= 3) {
-      chains.push(path20.slice(1).map((p) => `<- ${p}`).join(" "));
+    if (path19.length >= 3) {
+      chains.push(path19.slice(1).map((p) => `<- ${p}`).join(" "));
     }
   }
   return chains.sort();
@@ -4391,14 +4429,14 @@ function collectIndirectDependents(graph, directlyAffected) {
     }
     for (const [node] of parent) {
       if (directSet.has(node)) continue;
-      const path20 = [node];
+      const path19 = [node];
       let current = node;
       while (parent.has(current)) {
         current = parent.get(current);
-        path20.push(current);
+        path19.push(current);
       }
-      const chain = path20.map((p) => `<- ${p}`).join(" ");
-      const depth = path20.length;
+      const chain = path19.map((p) => `<- ${p}`).join(" ");
+      const depth = path19.length;
       const existing = bestChain.get(node);
       if (!existing || depth < existing.depth) {
         bestChain.set(node, { chain, depth });
@@ -4840,6 +4878,7 @@ function registerFlowsCommand(program2) {
           participants: flow.nodes.length,
           nodes: flow.nodes.sort()
         };
+        if (flow.description) entry.description = flow.description;
         if (flow.aspects && flow.aspects.length > 0) entry.aspects = flow.aspects;
         return entry;
       });