@chrisdudek/yg 0.1.0

package/dist/bin.js

@@ -0,0 +1,3294 @@
+#!/usr/bin/env node
+
+// src/bin.ts
+import { Command } from "commander";
+
+// src/cli/init.ts
+import { mkdir as mkdir2, writeFile as writeFile2, readdir, readFile as readFile2, stat } from "fs/promises";
+import path2 from "path";
+import { fileURLToPath } from "url";
+
+// src/templates/default-config.ts
+var DEFAULT_CONFIG = `name: ""
+
+stack:
+  language: ""
+  runtime: ""
+
+standards: ""
+
+tags: []
+
+node_types:
+  - module
+  - service
+  - library
+
+artifacts:
+  responsibility.md:
+    required: always
+    description: "What this node is responsible for, and what it is not"
+  interface.md:
+    required:
+      when: has_incoming_relations
+    description: "Public API \u2014 methods, parameters, return types, contracts"
+    structural_context: true
+  constraints.md:
+    required: never
+    description: "Validation rules, business rules, invariants"
+  errors.md:
+    required:
+      when: has_incoming_relations
+    description: "Error conditions, codes, recovery behavior"
+    structural_context: true
+  state.md:
+    required: never
+    description: "State machines, lifecycle, transitions"
+  decisions.md:
+    required: never
+    description: "Local design decisions and rationale"
+
+knowledge_categories:
+  - name: decisions
+    description: "Global semantic decisions and their rationale"
+  - name: patterns
+    description: "Implementation conventions with examples"
+  - name: invariants
+    description: "System truths that must never be violated"
+
+quality:
+  min_artifact_length: 50
+  max_direct_relations: 10
+  context_budget:
+    warning: 5000
+    error: 10000
+  knowledge_staleness_days: 90
+`;
+
+// src/templates/platform.ts
+import { readFile, writeFile, mkdir } from "fs/promises";
+import path from "path";
+
+// src/templates/rules.ts
+var AGENT_RULES_CONTENT = `# Yggdrasil - System Semantic Memory (Operating Manual)
+
+You are working in a repository managed by Yggdrasil.
+Yggdrasil is a persistent, structured semantic memory graph stored in \`.yggdrasil/\`. It maps the repository, dictates system rules, and assembles implementation contexts.
+
+THIS PROMPT IS YOUR ENTIRE OPERATING MANUAL. Read it carefully. Follow it strictly.
+
+---
+
+## 1. CORE PRINCIPLES (NON-NEGOTIABLE)
+
+1. **Graph First, Always:** Before answering a question, modifying code, or planning a feature, you MUST consult the graph.
+2. **Context is Sufficient:** If you feel the need to randomly explore source files to understand what a node should do, the graph is incomplete. **Fix the graph** (add decisions, interface details, constraints). Do not bypass the graph by reading raw code.
+3. **Graph is Intended Truth:** If the code and graph diverge, the graph is the truth. If a code change is deliberate, update the graph to match.
+4. **Exhaustive Coverage:** Every source file MUST belong to exactly one graph node. No orphaned files.
+5. **Tools Read, You Write:** The \`yg\` CLI tools only read, validate, and manage metadata. YOU must create and edit graph directories, \`.yaml\` files, and \`.md\` artifacts manually.
+6. **English Only for Artifacts:** All graph artifact files (filenames from \`config.artifacts\`, in the same directory as \`node.yaml\`) MUST be written in English. Conversation can be in the user's language.
+7. **Never Touch Operational Metadata:** NEVER manually edit \`.yggdrasil/.drift-state\` or \`.yggdrasil/.journal.yaml\`.
+
+---
+
+## 2. CONVERSATION LIFECYCLE (YOUR HABITS)
+
+You do not need explicit "session" commands. Follow these conversational triggers:
+
+### A. Preflight (First message of the conversation)
+Always execute these commands before doing anything else:
+1. \`yg journal-read\` -> If entries exist, consolidate them into the graph, then \`yg journal-archive\`.
+2. \`yg drift\` -> If divergence is detected, present states (\`ok\`, \`drift\`, \`missing\`, \`unmaterialized\`). Ask the user: Absorb (update graph) or Reject (re-materialize code from graph)?
+3. \`yg status\` -> Report graph health.
+4. \`yg validate\` -> If W008 stale-knowledge appears, update the knowledge artifacts to reflect current node state.
+
+### B. Wrap-up (User signals closing the topic)
+Triggered by phrases like: "ko\u0144czymy", "wrap up", "to tyle", "gotowe".
+**Note: The graph should ALREADY be up to date. Do not wait for wrap-up to update graph artifacts.**
+1. If iterative journal mode was used: consolidate notes to the graph, then \`yg journal-archive\`.
+2. \`yg drift\` -> Check if files changed manually during the conversation.
+3. \`yg validate\` -> Fix any structural errors.
+4. Report exactly what nodes and files were changed.
+
+---
+
+## 3. WORKFLOW: MODIFYING OR CREATING FILES
+
+You are NOT ALLOWED to edit or create source code without establishing graph coverage first.
+
+**Step 1: Check coverage** -> Run \`yg owner --file <path>\`
+
+**Step 2: If Owner FOUND (The Execution Checklist)**
+Whenever you write or edit source code, you MUST output this exact checklist in your response to the user, and execute each step BEFORE finishing your turn. This forces you to remember the graph:
+
+- [x] 1. Read Specification (ran \`yg build-context\`)
+- [x] 2. Modify Source Code
+- [x] 3. Sync Graph Artifacts (manually edit the node's artifact files \u2014 filenames from \`config.artifacts\` \u2014 IMMEDIATELY to match new code behavior)
+- [x] 4. Baseline Hash (ran \`yg drift-sync\` ONLY AFTER updating the graph)
+
+*If you do not print this checklist and check off step 3, you have failed the core directive of Yggdrasil.*
+
+**Step 3: If Owner NOT FOUND (Uncovered Area)**
+STOP. Do not modify the code. First determine: **Is this greenfield (empty or new code to be created)?**
+
+*   **If GREENFIELD (empty directory, new project, code not yet written):** Do NOT offer blackbox. Use Option 1 only \u2014 create proper nodes (reverse engineering or upfront design) before implementing. Blackbox is forbidden for new code.
+*   **If EXISTING CODE (legacy, third-party, shipped-but-unmapped):** Present the user with 3 options and wait for their decision:
+    *   **Option 1: Reverse Engineering:** Create/extend standard nodes to map the area fully before modifying.
+    *   **Option 2: Blackbox Coverage:** Create a \`blackbox: true\` node at a user-chosen granularity to establish ownership without deep semantic exploration.
+    *   **Option 3: Abort/Change Plan:** Do not touch the file.
+
+
+---
+
+## 4. WORKFLOW: MODIFYING THE GRAPH & BLAST RADIUS
+
+When adding features or changing architecture, update the graph FIRST.
+
+**DO NOT DEFER GRAPH UPDATES:**
+*   **DO NOT wait for the user to confirm if a change is "final".** The graph must evolve continuously with your code edits.
+*   **Default Behavior:** If iterative journal mode is OFF, you MUST write structural and semantic changes directly to the graph files (\`node.yaml\`, artifacts or other files like aspects or flows, etc.) IMMEDIATELY. Suppress your innate safety bias to wait for permission.
+
+1. **Check Blast Radius:** Before modifying a node that others depend on, run \`yg impact --node <node_path> --simulate\`. Report the impact to the user.
+2. **Read Config & Templates:**
+    *   Check \`.yggdrasil/config.yaml\` for allowed \`node_types\` and \`tags\`.
+    *   **CRITICAL:** ALWAYS read the required schema files in \`.yggdrasil/templates/\` (e.g., \`node.yaml\`, \`service.yaml\`) to know the exact fields and structure before creating or editing any graph file.
+3. **Validate & Fix:** Run \`yg validate\`. You must fix all E-codes (Errors).
+4. **Token Economy & W-codes (Warnings):**
+    *   If you see \`W005 budget-warning\` or \`W006 budget-error\`, the context package is too large. You MUST consider splitting the node or reducing dependencies.
+    *   If you see \`W008 stale-knowledge\`, the semantic memory is outdated compared to the code. Update the knowledge artifacts.
+    *   **Smallest Viable Scope:** Prefer \`scope: nodes\` over \`scope: tags\`. Prefer tags over \`scope: global\`. Global scope costs token budget in EVERY context package.
+
+**Journaling (Iterative Mode):**
+*   **Default:** Write changes directly to graph files immediately.
+*   **Opt-in:** ONLY if the user says "tryb iteracyjny" or "u\u017Cyj journala", use \`yg journal-add --note "..."\` to buffer intent during fast ping-pong changes.
+
+---
+
+## 5. PATH CONVENTIONS (CRITICAL)
+
+To avoid broken references (\`E004\`, \`E005\`), use correct relative paths:
+*   **Node paths** (used in CLI, relations, flow nodes): Relative to \`.yggdrasil/model/\` (e.g., \`orders/order-service\`).
+*   **File paths** (used in mapping, \`yg owner\`): Relative to the repository root (e.g., \`src/modules/orders/order.service.ts\`).
+*   **Knowledge paths** (used in node explicit refs): Relative to \`.yggdrasil/knowledge/\` (e.g., \`decisions/001-event-sourcing\`).
+
+---
+
+## 6. GRAPH STRUCTURE, CONFIG & TEMPLATES CHEAT SHEET
+
+The graph lives entirely under \`.yggdrasil/\`. You NEVER guess structure. You MUST ALWAYS read the corresponding schema reference in \`.yggdrasil/templates/\` before creating or editing any graph file.
+
+*   **\`.yggdrasil/config.yaml\`**: The ONLY config file. Defines \`node_types\`, \`tags\`, \`artifacts\`, \`knowledge_categories\`, and quality thresholds. Read this before any graph work.
+*   **\`.yggdrasil/templates/\`**: The SINGLE place for all templates and schemas.
+    *   Contains node-type templates (e.g., \`service.yaml\`, \`module.yaml\`) with suggested artifacts and guidance.
+    *   Contains schema references (\`node.yaml\`, \`aspect.yaml\`, \`flow.yaml\`, \`knowledge.yaml\`) showing exact file structures.
+*   **\`.yggdrasil/model/\`**: Node tree. Each node is a directory with \`node.yaml\` and artifact files (filenames from \`config.artifacts\`; required ones depend on config).
+*   **\`.yggdrasil/aspects/\`**: Cross-cutting rules. Directory contains \`aspect.yaml\` (binds via \`tag: <name>\`) and \`.md\` content.
+*   **\`.yggdrasil/flows/\`**: End-to-end processes. Directory contains \`flow.yaml\` (lists \`nodes: [paths]\` and \`knowledge: [paths]\`) and \`.md\` content.
+*   **\`.yggdrasil/knowledge/\`**: Repo-wide wisdom (\`decisions/\`, \`patterns/\`, \`invariants/\`). Directory contains \`knowledge.yaml\` and \`.md\` content.
+
+---
+
+## 7. CLI TOOLS REFERENCE (\`yg\`)
+
+Always use these exact commands.
+
+*   \`yg owner --file <file_path>\` -> Find owning node.
+*   \`yg build-context --node <node_path>\` -> Assemble strict specification.
+*   \`yg tree [--root <node_path>] [--depth N]\` -> Print graph structure.
+*   \`yg deps --node <node_path> [--type structural|event|all]\` -> Show dependencies.
+*   \`yg impact --node <node_path> --simulate\` -> Simulate blast radius.
+*   \`yg status\` -> Graph health metrics.
+*   \`yg validate [--scope <node_path>|all]\` -> Compile/check graph. Run after EVERY graph edit.
+*   \`yg drift [--scope <node_path>|all]\` -> Check code vs graph baseline.
+*   \`yg drift-sync --node <node_path>\` -> Save current file hash as new baseline. Run ONLY after ensuring graph artifacts match the code.
+
+*(Iterative mode only)*
+*   \`yg journal-read\`
+*   \`yg journal-add --note "<content>" [--target <node_path>]\`
+*   \`yg journal-archive\`
+`;
+
+// src/templates/platform.ts
+var AGENT_RULES_IMPORT = "@.yggdrasil/agent-rules.md";
+var YGGDRASIL_START = "<!-- yggdrasil:start -->";
+var YGGDRASIL_END = "<!-- yggdrasil:end -->";
+var YGGDRASIL_SECTION = `## Yggdrasil
+
+${AGENT_RULES_CONTENT}`;
+var YGGDRASIL_BLOCK = `${YGGDRASIL_START}
+${YGGDRASIL_SECTION}
+${YGGDRASIL_END}`;
+var PLATFORMS = [
+  "cursor",
+  "claude-code",
+  "copilot",
+  "cline",
+  "roocode",
+  "codex",
+  "windsurf",
+  "aider",
+  "gemini",
+  "amp",
+  "generic"
+];
+async function installRulesForPlatform(projectRoot, platform) {
+  const agentRulesPath = path.join(projectRoot, ".yggdrasil", "agent-rules.md");
+  switch (platform) {
+    case "cursor":
+      return installForCursor(projectRoot);
+    case "claude-code":
+      return installForClaudeCode(projectRoot, agentRulesPath);
+    case "copilot":
+      return installForCopilot(projectRoot);
+    case "cline":
+      return installForCline(projectRoot);
+    case "roocode":
+      return installForRooCode(projectRoot);
+    case "codex":
+      return installForCodex(projectRoot);
+    case "windsurf":
+      return installForWindsurf(projectRoot);
+    case "aider":
+      return installForAider(projectRoot, agentRulesPath);
+    case "gemini":
+      return installForGemini(projectRoot, agentRulesPath);
+    case "amp":
+      return installForAmp(projectRoot, agentRulesPath);
+    case "generic":
+    default:
+      return installForGeneric(projectRoot);
+  }
+}
+async function ensureAgentRules(agentRulesPath) {
+  await mkdir(path.dirname(agentRulesPath), { recursive: true });
+  await writeFile(agentRulesPath, AGENT_RULES_CONTENT, "utf-8");
+}
+async function installForCursor(projectRoot) {
+  const dir = path.join(projectRoot, ".cursor", "rules");
+  await mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, "yggdrasil.mdc");
+  const content = `---
+description: Yggdrasil \u2014 semantic memory of the repository
+alwaysApply: true
+---
+
+${AGENT_RULES_CONTENT}`;
+  await writeFile(filePath, content, "utf-8");
+  return filePath;
+}
+async function installForClaudeCode(projectRoot, agentRulesPath) {
+  await ensureAgentRules(agentRulesPath);
+  const filePath = path.join(projectRoot, "CLAUDE.md");
+  let existing = "";
+  try {
+    existing = await readFile(filePath, "utf-8");
+  } catch {
+  }
+  const importLine = AGENT_RULES_IMPORT;
+  if (existing.includes(importLine)) {
+    return agentRulesPath;
+  }
+  const content = existing.trimEnd() ? `${existing.trimEnd()}
+${importLine}
+` : `${importLine}
+`;
+  await writeFile(filePath, content, "utf-8");
+  return agentRulesPath;
+}
+async function installForCopilot(projectRoot) {
+  const dir = path.join(projectRoot, ".github");
+  await mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, "copilot-instructions.md");
+  let existing = "";
+  try {
+    existing = await readFile(filePath, "utf-8");
+  } catch {
+  }
+  let content;
+  if (existing.includes(YGGDRASIL_START) && existing.includes(YGGDRASIL_END)) {
+    content = existing.replace(
+      new RegExp(`${escapeRegex(YGGDRASIL_START)}[\\s\\S]*?${escapeRegex(YGGDRASIL_END)}`, "g"),
+      YGGDRASIL_BLOCK
+    );
+  } else {
+    content = existing.trimEnd() ? `${existing.trimEnd()}
+
+${YGGDRASIL_BLOCK}
+` : `${YGGDRASIL_BLOCK}
+`;
+  }
+  await writeFile(filePath, content, "utf-8");
+  return filePath;
+}
+async function installForCline(projectRoot) {
+  const dir = path.join(projectRoot, ".clinerules");
+  await mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, "yggdrasil.md");
+  await writeFile(filePath, AGENT_RULES_CONTENT, "utf-8");
+  return filePath;
+}
+async function installForRooCode(projectRoot) {
+  const dir = path.join(projectRoot, ".roo", "rules");
+  await mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, "yggdrasil.md");
+  await writeFile(filePath, AGENT_RULES_CONTENT, "utf-8");
+  return filePath;
+}
+async function installForCodex(projectRoot) {
+  const filePath = path.join(projectRoot, "AGENTS.md");
+  let existing = "";
+  try {
+    existing = await readFile(filePath, "utf-8");
+  } catch {
+  }
+  let content;
+  if (existing.includes(YGGDRASIL_START) && existing.includes(YGGDRASIL_END)) {
+    content = existing.replace(
+      new RegExp(`${escapeRegex(YGGDRASIL_START)}[\\s\\S]*?${escapeRegex(YGGDRASIL_END)}`, "g"),
+      YGGDRASIL_BLOCK
+    );
+  } else {
+    content = existing.trimEnd() ? `${existing.trimEnd()}
+
+${YGGDRASIL_BLOCK}
+` : `${YGGDRASIL_BLOCK}
+`;
+  }
+  await writeFile(filePath, content, "utf-8");
+  return filePath;
+}
+async function installForWindsurf(projectRoot) {
+  const dir = path.join(projectRoot, ".windsurf", "rules");
+  await mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, "yggdrasil.md");
+  await writeFile(filePath, AGENT_RULES_CONTENT, "utf-8");
+  return filePath;
+}
+async function installForAider(projectRoot, agentRulesPath) {
+  await ensureAgentRules(agentRulesPath);
+  const filePath = path.join(projectRoot, ".aider.conf.yml");
+  const entry = ".yggdrasil/agent-rules.md";
+  let existing = "";
+  try {
+    existing = await readFile(filePath, "utf-8");
+  } catch {
+  }
+  if (existing.includes(entry)) {
+    return agentRulesPath;
+  }
+  const content = appendAiderReadEntry(existing, entry);
+  await writeFile(filePath, content, "utf-8");
+  return agentRulesPath;
+}
+function appendAiderReadEntry(existing, entry) {
+  const newItem = `  - ${entry}  # added by yg init
+`;
+  const readBlock = /^read:\s*\n((?:\s+-\s+[^\n]+\n)*)/m;
+  const match = existing.match(readBlock);
+  if (match) {
+    return existing.replace(match[0], `read:
+${match[1]}${newItem}`);
+  }
+  const readEmpty = /^read:\s*$/m;
+  if (readEmpty.test(existing)) {
+    return existing.replace(readEmpty, `read:
+${newItem}`);
+  }
+  const trimmed = existing.trimEnd();
+  return trimmed ? `${trimmed}
+
+read:
+${newItem}` : `read:
+${newItem}`;
+}
+async function installForGemini(projectRoot, agentRulesPath) {
+  await ensureAgentRules(agentRulesPath);
+  const filePath = path.join(projectRoot, "GEMINI.md");
+  let existing = "";
+  try {
+    existing = await readFile(filePath, "utf-8");
+  } catch {
+  }
+  const importLine = AGENT_RULES_IMPORT;
+  if (existing.includes(importLine)) {
+    return agentRulesPath;
+  }
+  const content = existing.trimEnd() ? `${existing.trimEnd()}
+${importLine}
+` : `${importLine}
+`;
+  await writeFile(filePath, content, "utf-8");
+  return agentRulesPath;
+}
+async function installForAmp(projectRoot, agentRulesPath) {
+  await ensureAgentRules(agentRulesPath);
+  const filePath = path.join(projectRoot, "AGENTS.md");
+  let existing = "";
+  try {
+    existing = await readFile(filePath, "utf-8");
+  } catch {
+  }
+  const importLine = AGENT_RULES_IMPORT;
+  if (existing.includes(importLine)) {
+    return agentRulesPath;
+  }
+  const content = existing.trimEnd() ? `${existing.trimEnd()}
+${importLine}
+` : `${importLine}
+`;
+  await writeFile(filePath, content, "utf-8");
+  return agentRulesPath;
+}
+async function installForGeneric(projectRoot) {
+  const filePath = path.join(projectRoot, ".yggdrasil", "agent-rules.md");
+  await ensureAgentRules(filePath);
+  return filePath;
+}
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// src/cli/init.ts
+function getGraphTemplatesDir() {
+  const currentDir = path2.dirname(fileURLToPath(import.meta.url));
+  const packageRoot = path2.join(currentDir, "..");
+  return path2.join(packageRoot, "graph-templates");
+}
+var GITIGNORE_CONTENT = `.journal.yaml
+journals-archive/
+`;
+function registerInitCommand(program2) {
+  program2.command("init").description("Initialize Yggdrasil graph in current project").option(
+    "--platform <name>",
+    "Agent platform: cursor, claude-code, copilot, cline, roocode, codex, windsurf, aider, gemini, amp, generic",
+    "generic"
+  ).option("--upgrade", "Refresh rules only (when .yggdrasil/ already exists)").action(async (options) => {
+    const projectRoot = process.cwd();
+    const yggRoot = path2.join(projectRoot, ".yggdrasil");
+    let upgradeMode = false;
+    try {
+      const statResult = await stat(yggRoot);
+      if (!statResult.isDirectory()) {
+        process.stderr.write("Error: .yggdrasil exists but is not a directory.\n");
+        process.exit(1);
+      }
+      if (options.upgrade) {
+        upgradeMode = true;
+      } else {
+        process.stderr.write(
+          "Error: .yggdrasil/ already exists. Use --upgrade to refresh rules only.\n"
+        );
+        process.exit(1);
+      }
+    } catch {
+    }
+    const platform = options.platform ?? "generic";
+    if (!PLATFORMS.includes(platform)) {
+      process.stderr.write(
+        `Error: Unknown platform '${platform}'. Use: ${PLATFORMS.join(", ")}
+`
+      );
+      process.exit(1);
+    }
+    if (upgradeMode) {
+      const rulesPath2 = await installRulesForPlatform(projectRoot, platform);
+      process.stdout.write("\u2713 Rules refreshed.\n");
+      process.stdout.write(`  ${path2.relative(projectRoot, rulesPath2)}
+`);
+      return;
+    }
+    await mkdir2(path2.join(yggRoot, "model"), { recursive: true });
+    await mkdir2(path2.join(yggRoot, "aspects"), { recursive: true });
+    await mkdir2(path2.join(yggRoot, "flows"), { recursive: true });
+    await mkdir2(path2.join(yggRoot, "knowledge", "decisions"), { recursive: true });
+    await mkdir2(path2.join(yggRoot, "knowledge", "patterns"), { recursive: true });
+    await mkdir2(path2.join(yggRoot, "knowledge", "invariants"), { recursive: true });
+    const templatesDir = path2.join(yggRoot, "templates");
+    await mkdir2(templatesDir, { recursive: true });
+    const graphTemplatesDir = getGraphTemplatesDir();
+    try {
+      const entries = await readdir(graphTemplatesDir, { withFileTypes: true });
+      const templateFiles = entries.filter((e) => e.isFile()).map((e) => e.name);
+      for (const file of templateFiles) {
+        const srcPath = path2.join(graphTemplatesDir, file);
+        const content = await readFile2(srcPath, "utf-8");
+        await writeFile2(path2.join(templatesDir, file), content, "utf-8");
+      }
+    } catch (err) {
+      process.stderr.write(
+        `Warning: Could not copy graph templates from ${graphTemplatesDir}: ${err.message}
+`
+      );
+    }
+    await writeFile2(path2.join(yggRoot, "config.yaml"), DEFAULT_CONFIG, "utf-8");
+    await writeFile2(path2.join(yggRoot, ".gitignore"), GITIGNORE_CONTENT, "utf-8");
+    const rulesPath = await installRulesForPlatform(projectRoot, platform);
+    process.stdout.write("\u2713 Yggdrasil initialized.\n\n");
+    process.stdout.write("Created:\n");
+    process.stdout.write("  .yggdrasil/config.yaml\n");
+    process.stdout.write("  .yggdrasil/.gitignore\n");
+    process.stdout.write("  .yggdrasil/model/\n");
+    process.stdout.write("  .yggdrasil/aspects/\n");
+    process.stdout.write("  .yggdrasil/flows/\n");
+    process.stdout.write("  .yggdrasil/knowledge/ (decisions, patterns, invariants)\n");
+    process.stdout.write(
+      "  .yggdrasil/templates/ (module, service, library, node, aspect, flow, knowledge)\n"
+    );
+    process.stdout.write(`  ${path2.relative(projectRoot, rulesPath)} (rules)
+
+`);
+    process.stdout.write("Next steps:\n");
+    process.stdout.write("  1. Edit .yggdrasil/config.yaml \u2014 set name, stack, standards\n");
+    process.stdout.write("  2. Create nodes under .yggdrasil/model/\n");
+    process.stdout.write("  3. Run: yg validate\n");
+  });
+}
+
+// src/core/graph-loader.ts
+import { readdir as readdir3 } from "fs/promises";
+import path5 from "path";
+
+// src/io/config-parser.ts
+import { readFile as readFile3 } from "fs/promises";
+import { parse as parseYaml } from "yaml";
+var DEFAULT_QUALITY = {
+  min_artifact_length: 50,
+  max_direct_relations: 10,
+  context_budget: { warning: 5e3, error: 1e4 },
+  knowledge_staleness_days: 90
+};
+async function parseConfig(filePath) {
+  const content = await readFile3(filePath, "utf-8");
+  const raw = parseYaml(content);
+  if (!raw.name || typeof raw.name !== "string" || raw.name.trim() === "") {
+    throw new Error(`config.yaml: missing or invalid 'name' field`);
+  }
+  const nodeTypes = raw.node_types;
+  if (!Array.isArray(nodeTypes) || nodeTypes.length === 0) {
+    throw new Error(`config.yaml: 'node_types' must be a non-empty array`);
+  }
+  const artifacts = raw.artifacts;
+  if (!artifacts || typeof artifacts !== "object" || Array.isArray(artifacts) || Object.keys(artifacts).length === 0) {
+    throw new Error(`config.yaml: 'artifacts' must be a non-empty object`);
+  }
+  const artifactsMap = {};
+  for (const [key, val] of Object.entries(artifacts)) {
+    if (key === "node") {
+      throw new Error(`config.yaml: artifact name 'node' is reserved`);
+    }
+    const a = val;
+    const required = a.required;
+    if (required !== "always" && required !== "never" && (typeof required !== "object" || !required || !("when" in required))) {
+      throw new Error(`config.yaml: artifact '${key}' has invalid 'required' field`);
+    }
+    if (typeof required === "object" && required && "when" in required) {
+      const when = required.when;
+      const validWhen = when === "has_incoming_relations" || when === "has_outgoing_relations" || typeof when === "string" && when.startsWith("has_tag:");
+      if (!validWhen) {
+        throw new Error(
+          `config.yaml: artifact '${key}' has invalid 'required.when': must be has_incoming_relations, has_outgoing_relations, or has_tag:<name>`
+        );
+      }
+    }
+    artifactsMap[key] = {
+      required,
+      description: a.description ?? "",
+      structural_context: a.structural_context ?? false
+    };
+  }
+  if (!("knowledge_categories" in raw)) {
+    throw new Error(
+      `config.yaml: missing 'knowledge_categories' field (required, may be empty list)`
+    );
+  }
+  const knowledgeCategoriesRaw = raw.knowledge_categories;
+  if (!Array.isArray(knowledgeCategoriesRaw)) {
+    throw new Error(`config.yaml: 'knowledge_categories' must be an array`);
+  }
+  const knowledgeCategories = knowledgeCategoriesRaw;
+  const categoryNames = /* @__PURE__ */ new Set();
+  for (const kc of knowledgeCategories) {
+    if (!kc?.name || typeof kc.name !== "string") continue;
+    if (categoryNames.has(kc.name)) {
+      throw new Error(`config.yaml: duplicate knowledge category '${kc.name}'`);
+    }
+    categoryNames.add(kc.name);
+  }
+  const qualityRaw = raw.quality;
+  const quality = qualityRaw ? {
+    min_artifact_length: qualityRaw.min_artifact_length ?? DEFAULT_QUALITY.min_artifact_length,
+    max_direct_relations: qualityRaw.max_direct_relations ?? DEFAULT_QUALITY.max_direct_relations,
+    context_budget: {
+      warning: qualityRaw.context_budget?.warning ?? DEFAULT_QUALITY.context_budget.warning,
+      error: qualityRaw.context_budget?.error ?? DEFAULT_QUALITY.context_budget.error
+    },
+    knowledge_staleness_days: qualityRaw.knowledge_staleness_days ?? DEFAULT_QUALITY.knowledge_staleness_days
+  } : DEFAULT_QUALITY;
+  if (quality.context_budget.error < quality.context_budget.warning) {
+    throw new Error(
+      `config.yaml: quality.context_budget.error (${quality.context_budget.error}) must be >= warning (${quality.context_budget.warning})`
+    );
+  }
+  if (!("tags" in raw)) {
+    throw new Error(`config.yaml: missing 'tags' field (required, may be empty list)`);
+  }
+  const tags = raw.tags;
+  if (!Array.isArray(tags)) {
+    throw new Error(`config.yaml: 'tags' must be an array`);
+  }
+  const tagsList = tags.filter((t) => typeof t === "string");
+  return {
+    name: raw.name.trim(),
+    stack: raw.stack ?? {},
+    standards: typeof raw.standards === "string" ? raw.standards : "",
+    tags: tagsList,
+    node_types: nodeTypes,
+    artifacts: artifactsMap,
+    knowledge_categories: knowledgeCategories.filter((kc) => kc?.name),
+    quality
+  };
+}
+
+// src/io/node-parser.ts
+import { readFile as readFile4 } from "fs/promises";
+import { parse as parseYaml2 } from "yaml";
+var RELATION_TYPES = [
+  "uses",
+  "calls",
+  "extends",
+  "implements",
+  "emits",
+  "listens"
+];
+function isValidRelationType(t) {
+  return typeof t === "string" && RELATION_TYPES.includes(t);
+}
+async function parseNodeYaml(filePath) {
+  const content = await readFile4(filePath, "utf-8");
+  const raw = parseYaml2(content);
+  if (!raw.name || typeof raw.name !== "string" || raw.name.trim() === "") {
+    throw new Error(`node.yaml at ${filePath}: missing or empty 'name'`);
+  }
+  if (!raw.type || typeof raw.type !== "string" || raw.type.trim() === "") {
+    throw new Error(`node.yaml at ${filePath}: missing or empty 'type'`);
+  }
+  const relations = parseRelations(raw.relations, filePath);
+  const mapping = parseMapping(raw.mapping, filePath);
+  return {
+    name: raw.name.trim(),
+    type: raw.type.trim(),
+    tags: parseStringArray(raw.tags),
+    blackbox: raw.blackbox ?? false,
+    relations: relations.length > 0 ? relations : void 0,
+    knowledge: parseStringArray(raw.knowledge),
+    mapping
+  };
+}
+function parseStringArray(val) {
+  if (!Array.isArray(val)) return void 0;
+  const arr = val.filter((v) => typeof v === "string");
+  return arr.length > 0 ? arr : void 0;
+}
+function parseRelations(raw, filePath) {
+  if (raw === void 0) return [];
+  if (!Array.isArray(raw)) {
+    throw new Error(`node.yaml at ${filePath}: 'relations' must be an array`);
+  }
+  const result = [];
+  for (let index = 0; index < raw.length; index++) {
+    const r = raw[index];
+    if (typeof r !== "object" || r === null) {
+      throw new Error(`node.yaml at ${filePath}: relations[${index}] must be an object`);
+    }
+    const obj = r;
+    const target = obj.target;
+    const type = obj.type;
+    if (typeof target !== "string" || target.trim() === "") {
+      throw new Error(
+        `node.yaml at ${filePath}: relations[${index}].target must be a non-empty string`
+      );
+    }
+    if (!isValidRelationType(type)) {
+      throw new Error(`node.yaml at ${filePath}: relations[${index}].type is invalid`);
+    }
+    const rel = {
+      target: target.trim(),
+      type
+    };
+    if (Array.isArray(obj.consumes)) {
+      rel.consumes = obj.consumes.filter((c) => typeof c === "string");
+    }
+    if (typeof obj.failure === "string") {
+      rel.failure = obj.failure;
+    }
+    if (typeof obj.event_name === "string" && obj.event_name.trim()) {
+      rel.event_name = obj.event_name.trim();
+    }
+    result.push(rel);
+  }
+  return result;
+}
+function validateRelativePath(pathValue, filePath, fieldName) {
+  const normalized = pathValue.trim();
+  if (normalized === "") {
+    throw new Error(`node.yaml at ${filePath}: '${fieldName}' must be non-empty`);
+  }
+  if (normalized.startsWith("/")) {
+    throw new Error(`node.yaml at ${filePath}: '${fieldName}' must be relative to repository root`);
+  }
+  return normalized;
+}
+function parseMapping(rawMapping, filePath) {
+  if (!rawMapping || typeof rawMapping !== "object") return void 0;
+  const obj = rawMapping;
+  if (Array.isArray(obj.paths) && obj.paths.length > 0) {
+    const paths = obj.paths.filter((p) => typeof p === "string").map((p) => validateRelativePath(p, filePath, "mapping.paths[]"));
+    if (paths.length === 0) {
+      throw new Error(`node.yaml at ${filePath}: mapping.paths must be a non-empty array`);
+    }
+    return { paths };
+  }
+  if (obj.paths !== void 0 || obj.type !== void 0 || obj.path !== void 0) {
+    throw new Error(
+      `node.yaml at ${filePath}: mapping must have paths (array of file/directory paths)`
+    );
+  }
+  return void 0;
+}
+
+// src/io/aspect-parser.ts
+import { readFile as readFile6 } from "fs/promises";
+import { parse as parseYaml3 } from "yaml";
+
+// src/io/artifact-reader.ts
+import { readFile as readFile5, readdir as readdir2 } from "fs/promises";
+import path3 from "path";
+async function readArtifacts(dirPath, excludeFiles = ["node.yaml"], includeFiles) {
+  const entries = await readdir2(dirPath, { withFileTypes: true });
+  const artifacts = [];
+  const includeSet = includeFiles && includeFiles.length > 0 ? new Set(includeFiles) : null;
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    if (excludeFiles.includes(entry.name)) continue;
+    if (includeSet && !includeSet.has(entry.name)) continue;
+    const filePath = path3.join(dirPath, entry.name);
+    const content = await readFile5(filePath, "utf-8");
+    artifacts.push({ filename: entry.name, content });
+  }
+  artifacts.sort((a, b) => a.filename.localeCompare(b.filename));
+  return artifacts;
+}
+
+// src/io/aspect-parser.ts
+async function parseAspect(aspectDir, aspectYamlPath) {
+  const content = await readFile6(aspectYamlPath, "utf-8");
+  const raw = parseYaml3(content);
+  if (!raw.name || typeof raw.name !== "string" || raw.name.trim() === "") {
+    throw new Error(`Aspect file ${aspectYamlPath}: missing or empty 'name'`);
+  }
+  if (!raw.tag || typeof raw.tag !== "string" || raw.tag.trim() === "") {
+    throw new Error(`Aspect file ${aspectYamlPath}: missing or empty 'tag'`);
+  }
+  const artifacts = await readArtifacts(aspectDir, ["aspect.yaml"]);
+  return {
+    name: raw.name.trim(),
+    tag: raw.tag.trim(),
+    artifacts
+  };
+}
+
+// src/io/flow-parser.ts
+import { readFile as readFile7 } from "fs/promises";
+import { parse as parseYaml4 } from "yaml";
+async function parseFlow(flowDir, flowYamlPath) {
+  const content = await readFile7(flowYamlPath, "utf-8");
+  const raw = parseYaml4(content);
+  if (!raw.name || typeof raw.name !== "string" || raw.name.trim() === "") {
+    throw new Error(`flow.yaml at ${flowYamlPath}: missing or empty 'name'`);
+  }
+  const nodes = raw.nodes;
+  if (!Array.isArray(nodes) || nodes.length === 0) {
+    throw new Error(`flow.yaml at ${flowYamlPath}: 'nodes' must be a non-empty array`);
+  }
+  const nodePaths = nodes.filter((n) => typeof n === "string");
+  if (nodePaths.length === 0) {
+    throw new Error(`flow.yaml at ${flowYamlPath}: 'nodes' must contain string node paths`);
+  }
+  const knowledge = Array.isArray(raw.knowledge) ? raw.knowledge.filter((k) => typeof k === "string") : void 0;
+  const artifacts = await readArtifacts(flowDir, ["flow.yaml"]);
+  return {
+    name: raw.name.trim(),
+    nodes: nodePaths,
+    knowledge,
+    artifacts
+  };
+}
+
+// src/io/knowledge-parser.ts
+import { readFile as readFile8 } from "fs/promises";
+import { parse as parseYaml5 } from "yaml";
+async function parseKnowledge(knowledgeDir, knowledgeYamlPath, category, relativePath) {
+  const content = await readFile8(knowledgeYamlPath, "utf-8");
+  const raw = parseYaml5(content);
+  if (!raw.name || typeof raw.name !== "string" || raw.name.trim() === "") {
+    throw new Error(`knowledge.yaml at ${knowledgeYamlPath}: missing or empty 'name'`);
+  }
+  const scope = parseScope(raw.scope, knowledgeYamlPath);
+  const artifacts = await readArtifacts(knowledgeDir, ["knowledge.yaml"]);
+  return {
+    name: raw.name.trim(),
+    scope,
+    category,
+    path: relativePath,
+    artifacts
+  };
+}
+function parseScope(raw, filePath) {
+  if (raw === "global") {
+    return "global";
+  }
+  if (raw && typeof raw === "object") {
+    const obj = raw;
+    if (Array.isArray(obj.tags)) {
+      const tags = obj.tags.filter((t) => typeof t === "string");
+      if (tags.length === 0) {
+        throw new Error(`knowledge.yaml at ${filePath}: scope.tags must be a non-empty array`);
+      }
+      return { tags };
+    }
+    if (Array.isArray(obj.nodes)) {
+      const nodes = obj.nodes.filter((n) => typeof n === "string");
+      if (nodes.length === 0) {
+        throw new Error(`knowledge.yaml at ${filePath}: scope.nodes must be a non-empty array`);
+      }
+      return { nodes };
+    }
+  }
+  throw new Error(`knowledge.yaml at ${filePath}: invalid 'scope' value`);
+}
+
+// src/io/template-parser.ts
+import { readFile as readFile9 } from "fs/promises";
+import { parse as parseYaml6 } from "yaml";
+async function parseTemplate(filePath) {
+  const content = await readFile9(filePath, "utf-8");
+  const raw = parseYaml6(content);
+  if (!raw.node_type || typeof raw.node_type !== "string" || raw.node_type.trim() === "") {
+    throw new Error(`template at ${filePath}: missing or empty 'node_type'`);
+  }
+  const suggestedArtifacts = Array.isArray(raw.suggested_artifacts) ? raw.suggested_artifacts.filter((a) => typeof a === "string") : void 0;
+  return {
+    nodeType: raw.node_type.trim(),
+    suggestedArtifacts: suggestedArtifacts && suggestedArtifacts.length > 0 ? suggestedArtifacts : void 0,
+    guidance: typeof raw.guidance === "string" ? raw.guidance : void 0
+  };
+}
+
+// src/utils/paths.ts
+import path4 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { stat as stat2 } from "fs/promises";
+async function findYggRoot(projectRoot) {
+  let current = path4.resolve(projectRoot);
+  const root = path4.parse(current).root;
+  while (true) {
+    const yggPath = path4.join(current, ".yggdrasil");
+    try {
+      const st = await stat2(yggPath);
+      if (!st.isDirectory()) {
+        throw new Error(
+          `.yggdrasil exists but is not a directory (${yggPath}). Run 'yg init' in a clean location.`
+        );
+      }
+      return yggPath;
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        if (current === root) {
+          throw new Error(`No .yggdrasil/ directory found. Run 'yg init' first.`, { cause: err });
+        }
+        current = path4.dirname(current);
+        continue;
+      }
+      throw err;
+    }
+  }
+}
+function normalizeMappingPaths(mapping) {
+  if (!mapping?.paths?.length) return [];
+  return mapping.paths.map((p) => p.trim()).filter(Boolean);
+}
+function normalizeProjectRelativePath(projectRoot, rawPath) {
+  const normalizedInput = rawPath.trim().replace(/\\/g, "/");
+  if (normalizedInput.length === 0) {
+    throw new Error("Path cannot be empty");
+  }
+  const absolute = path4.resolve(projectRoot, normalizedInput);
+  const relative = path4.relative(projectRoot, absolute);
+  const isOutside = relative.startsWith("..") || path4.isAbsolute(relative);
+  if (isOutside) {
+    throw new Error(`Path is outside project root: ${rawPath}`);
+  }
+  return relative.split(path4.sep).join("/");
+}
+
+// src/core/graph-loader.ts
+function toModelPath(absolutePath, modelDir) {
+  return path5.relative(modelDir, absolutePath).split(path5.sep).join("/");
+}
+var FALLBACK_CONFIG = {
+  name: "",
+  stack: {},
+  standards: "",
+  tags: [],
+  node_types: [],
+  artifacts: {},
+  knowledge_categories: []
+};
+async function loadGraph(projectRoot, options = {}) {
+  const yggRoot = await findYggRoot(projectRoot);
+  let configError;
+  let config = FALLBACK_CONFIG;
+  try {
+    config = await parseConfig(path5.join(yggRoot, "config.yaml"));
+  } catch (error) {
+    if (!options.tolerateInvalidConfig) {
+      throw error;
+    }
+    configError = error.message;
+  }
+  const modelDir = path5.join(yggRoot, "model");
+  const nodes = /* @__PURE__ */ new Map();
+  const nodeParseErrors = [];
+  const artifactFilenames = Object.keys(config.artifacts ?? {});
+  try {
+    await scanModelDirectory(modelDir, modelDir, null, nodes, nodeParseErrors, artifactFilenames);
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      throw new Error(`Directory .yggdrasil/model/ does not exist. Run 'yg init' first.`, {
+        cause: err
+      });
+    }
+    throw err;
+  }
+  const aspects = await loadAspects(path5.join(yggRoot, "aspects"));
+  const flows = await loadFlows(path5.join(yggRoot, "flows"));
+  const knowledge = await loadKnowledge(
+    path5.join(yggRoot, "knowledge"),
+    config.knowledge_categories
+  );
+  const templates = await loadTemplates(path5.join(yggRoot, "templates"));
+  return {
+    config,
+    configError,
+    nodeParseErrors: nodeParseErrors.length > 0 ? nodeParseErrors : void 0,
+    nodes,
+    aspects,
+    flows,
+    knowledge,
+    templates,
+    rootPath: yggRoot
+  };
+}
+async function scanModelDirectory(dirPath, modelDir, parent, nodes, nodeParseErrors, artifactFilenames) {
+  const entries = await readdir3(dirPath, { withFileTypes: true });
+  const hasNodeYaml = entries.some((e) => e.isFile() && e.name === "node.yaml");
+  if (!hasNodeYaml && dirPath !== modelDir) {
+    return;
+  }
+  if (hasNodeYaml) {
+    const graphPath = toModelPath(dirPath, modelDir);
+    let meta;
+    try {
+      meta = await parseNodeYaml(path5.join(dirPath, "node.yaml"));
+    } catch (err) {
+      nodeParseErrors.push({
+        nodePath: graphPath,
+        message: err.message
+      });
+      return;
+    }
+    const artifacts = await readArtifacts(dirPath, ["node.yaml"], artifactFilenames);
+    const node = {
+      path: graphPath,
+      meta,
+      artifacts,
+      children: [],
+      parent
+    };
+    nodes.set(graphPath, node);
+    if (parent) {
+      parent.children.push(node);
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith(".")) continue;
+      await scanModelDirectory(
+        path5.join(dirPath, entry.name),
+        modelDir,
+        node,
+        nodes,
+        nodeParseErrors,
+        artifactFilenames
+      );
+    }
+  } else {
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith(".")) continue;
+      await scanModelDirectory(
+        path5.join(dirPath, entry.name),
+        modelDir,
+        null,
+        nodes,
+        nodeParseErrors,
+        artifactFilenames
+      );
+    }
+  }
+}
+async function loadAspects(aspectsDir) {
+  try {
+    const entries = await readdir3(aspectsDir, { withFileTypes: true });
+    const aspects = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const aspectYamlPath = path5.join(aspectsDir, entry.name, "aspect.yaml");
+      const aspect = await parseAspect(path5.join(aspectsDir, entry.name), aspectYamlPath);
+      aspects.push(aspect);
+    }
+    return aspects;
+  } catch {
+    return [];
+  }
+}
+async function loadFlows(flowsDir) {
+  try {
+    const entries = await readdir3(flowsDir, { withFileTypes: true });
+    const flows = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const flowYamlPath = path5.join(flowsDir, entry.name, "flow.yaml");
+      const flow = await parseFlow(path5.join(flowsDir, entry.name), flowYamlPath);
+      flows.push(flow);
+    }
+    return flows;
+  } catch {
+    return [];
+  }
+}
+async function loadKnowledge(knowledgeDir, categories) {
+  const items = [];
+  const categorySet = new Set(categories.map((c) => c.name));
+  try {
+    const catEntries = await readdir3(knowledgeDir, { withFileTypes: true });
+    for (const catEntry of catEntries) {
+      if (!catEntry.isDirectory()) continue;
+      if (!categorySet.has(catEntry.name)) continue;
+      const catPath = path5.join(knowledgeDir, catEntry.name);
+      const itemEntries = await readdir3(catPath, { withFileTypes: true });
+      for (const itemEntry of itemEntries) {
+        if (!itemEntry.isDirectory()) continue;
+        const itemDir = path5.join(catPath, itemEntry.name);
+        const knowledgeYamlPath = path5.join(itemDir, "knowledge.yaml");
+        const relativePath = `${catEntry.name}/${itemEntry.name}`;
+        const item = await parseKnowledge(itemDir, knowledgeYamlPath, catEntry.name, relativePath);
+        items.push(item);
+      }
+    }
+  } catch {
+  }
+  return items;
+}
+async function loadTemplates(templatesDir) {
+  try {
+    const entries = await readdir3(templatesDir, { withFileTypes: true });
+    const templates = [];
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      if (!entry.name.endsWith(".yaml") && !entry.name.endsWith(".yml")) continue;
+      const t = await parseTemplate(path5.join(templatesDir, entry.name));
+      templates.push(t);
+    }
+    return templates;
+  } catch {
+    return [];
+  }
+}
+
+// src/core/context-builder.ts
+import { readFile as readFile10 } from "fs/promises";
+import path6 from "path";
+
+// src/utils/tokens.ts
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+
+// 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"]);
+async function buildContext(graph, nodePath) {
+  const node = graph.nodes.get(nodePath);
+  if (!node) {
+    throw new Error(`Node not found: ${nodePath}`);
+  }
+  const nodeTags = new Set(node.meta.tags ?? []);
+  const seenKnowledge = /* @__PURE__ */ new Set();
+  const layers = [];
+  layers.push(buildGlobalLayer(graph.config));
+  for (const k of collectKnowledgeItems(graph, nodePath, nodeTags, seenKnowledge)) {
+    layers.push(buildKnowledgeLayer(k));
+  }
+  const ancestors = collectAncestors(node);
+  for (const ancestor of ancestors) {
+    layers.push(buildHierarchyLayer(ancestor, graph.config));
+  }
+  layers.push(await buildOwnLayer(node, graph.config, graph.rootPath));
+  for (const relation of node.meta.relations ?? []) {
+    const target = graph.nodes.get(relation.target);
+    if (!target) {
+      throw new Error(`Broken relation: ${nodePath} -> ${relation.target} (target not found)`);
+    }
+    if (STRUCTURAL_RELATION_TYPES.has(relation.type)) {
+      layers.push(buildStructuralRelationLayer(target, relation, graph.config));
+    } else if (EVENT_RELATION_TYPES.has(relation.type)) {
+      layers.push(buildEventRelationLayer(target, relation));
+    }
+  }
+  for (const tag of nodeTags) {
+    for (const aspect of graph.aspects) {
+      if (aspect.tag === tag) {
+        layers.push(buildAspectLayer(aspect));
+      }
+    }
+  }
+  for (const flow of collectParticipatingFlows(graph, nodePath)) {
+    layers.push(buildFlowLayer(flow));
+    for (const kPath of flow.knowledge ?? []) {
+      const norm = kPath.replace(/\/$/, "");
+      const k = graph.knowledge.find((item) => item.path === norm || item.path === kPath);
+      if (k && !seenKnowledge.has(k.path)) {
+        seenKnowledge.add(k.path);
+        layers.push(buildKnowledgeLayer(k, true));
+      }
+    }
+  }
+  const fullText = layers.map((l) => l.content).join("\n\n");
+  const tokenCount = estimateTokens(fullText);
+  const mapping = normalizeMappingPaths(node.meta.mapping);
+  const sections = buildSections(layers, mapping.length > 0 ? mapping : null);
+  return {
+    nodePath,
+    nodeName: node.meta.name,
+    layers,
+    sections,
+    mapping: mapping.length > 0 ? mapping : null,
+    tokenCount
+  };
+}
+function collectKnowledgeItems(graph, nodePath, nodeTags, seenKnowledge) {
+  const result = [];
+  for (const k of graph.knowledge) {
+    if (k.scope === "global" && !seenKnowledge.has(k.path)) {
+      seenKnowledge.add(k.path);
+      result.push(k);
+    }
+  }
+  for (const k of graph.knowledge) {
+    if (typeof k.scope === "object" && "tags" in k.scope) {
+      const overlap = k.scope.tags.some((t) => nodeTags.has(t));
+      if (overlap && !seenKnowledge.has(k.path)) {
+        seenKnowledge.add(k.path);
+        result.push(k);
+      }
+    }
+  }
+  for (const k of graph.knowledge) {
+    if (typeof k.scope === "object" && "nodes" in k.scope) {
+      if (k.scope.nodes.includes(nodePath) && !seenKnowledge.has(k.path)) {
+        seenKnowledge.add(k.path);
+        result.push(k);
+      }
+    }
+  }
+  const node = graph.nodes.get(nodePath);
+  if (node?.meta.knowledge) {
+    for (const kPath of node.meta.knowledge) {
+      const norm = kPath.replace(/\/$/, "");
+      const k = graph.knowledge.find((item) => item.path === norm || item.path === kPath);
+      if (k && !seenKnowledge.has(k.path)) {
+        seenKnowledge.add(k.path);
+        result.push(k);
+      }
+    }
+  }
+  return result;
+}
+function collectParticipatingFlows(graph, nodePath) {
+  return graph.flows.filter((f) => f.nodes.includes(nodePath));
+}
+function buildGlobalLayer(config) {
+  let content = `**Project:** ${config.name}
+
+`;
+  content += `**Stack:**
+`;
+  for (const [key, value] of Object.entries(config.stack)) {
+    content += `- ${key}: ${value}
+`;
+  }
+  content += `
+**Standards:**
+${config.standards || "(none)"}
+`;
+  return { type: "global", label: "Global Context", content };
+}
+function buildKnowledgeLayer(k, fromFlow) {
+  const categoryLabel = k.category.charAt(0).toUpperCase() + k.category.slice(1);
+  const content = k.artifacts.map((a) => `### ${a.filename}
+${a.content}`).join("\n\n");
+  const label = fromFlow ? `Long-term Memory (from flow): ${k.name}` : `${categoryLabel}: ${k.name}`;
+  return {
+    type: "knowledge",
+    label,
+    content
+  };
+}
+function filterArtifactsByConfig(artifacts, config) {
+  const allowed = new Set(Object.keys(config.artifacts ?? {}));
+  return artifacts.filter((a) => allowed.has(a.filename));
+}
+function buildHierarchyLayer(ancestor, config) {
+  const filtered = filterArtifactsByConfig(ancestor.artifacts, config);
+  const content = filtered.map((a) => `### ${a.filename}
+${a.content}`).join("\n\n");
+  return {
+    type: "hierarchy",
+    label: `Module Context (${ancestor.path}/)`,
+    content
+  };
+}
+async function buildOwnLayer(node, config, graphRootPath) {
+  const parts = [];
+  const nodeYamlPath = path6.join(graphRootPath, "model", node.path, "node.yaml");
+  try {
+    const nodeYamlContent = await readFile10(nodeYamlPath, "utf-8");
+    parts.push(`### node.yaml
+${nodeYamlContent.trim()}`);
+  } catch {
+    parts.push(`### node.yaml
+(not found)`);
+  }
+  const filtered = filterArtifactsByConfig(node.artifacts, config);
+  for (const a of filtered) {
+    parts.push(`### ${a.filename}
+${a.content}`);
+  }
+  const content = parts.join("\n\n");
+  return {
+    type: "own",
+    label: `Node: ${node.meta.name}`,
+    content
+  };
+}
+function buildStructuralRelationLayer(target, relation, config) {
+  let content = "";
+  if (relation.consumes?.length) {
+    content += `Consumes: ${relation.consumes.join(", ")}
+
+`;
+  }
+  if (relation.failure) {
+    content += `On failure: ${relation.failure}
+
+`;
+  }
+  const structuralArtifactFilenames = Object.entries(config.artifacts ?? {}).filter(([, c]) => c.structural_context).map(([filename]) => filename);
+  const structuralArts = structuralArtifactFilenames.map((filename) => {
+    const art = target.artifacts.find((a) => a.filename === filename);
+    return art ? { filename: art.filename, content: art.content } : null;
+  }).filter((a) => a !== null);
+  if (structuralArts.length > 0) {
+    content += structuralArts.map((a) => `### ${a.filename}
+${a.content}`).join("\n\n");
+  } else {
+    const filtered = filterArtifactsByConfig(target.artifacts, config);
+    content += filtered.map((a) => `### ${a.filename}
+${a.content}`).join("\n\n");
+  }
+  return {
+    type: "relational",
+    label: `Dependency: ${target.meta.name} (${relation.type}) \u2014 ${target.path}`,
+    content: content.trim()
+  };
+}
+function buildEventRelationLayer(target, relation) {
+  const eventName = relation.event_name ?? target.meta.name;
+  const isEmit = relation.type === "emits";
+  let content = isEmit ? `Target: ${target.path}
+You publish ${eventName}.` : `Source: ${target.path}
+You listen for ${eventName}.`;
+  if (relation.consumes?.length) {
+    content += `
+Consumes: ${relation.consumes.join(", ")}`;
+  }
+  return {
+    type: "relational",
+    label: `Event: ${eventName} [${relation.type}]`,
+    content
+  };
+}
+function buildAspectLayer(aspect) {
+  const content = aspect.artifacts.map((a) => `### ${a.filename}
+${a.content}`).join("\n\n");
+  return {
+    type: "aspects",
+    label: `${aspect.name} (tag: ${aspect.tag})`,
+    content
+  };
+}
+function buildFlowLayer(flow) {
+  const content = flow.artifacts.map((a) => `### ${a.filename}
+${a.content}`).join("\n\n");
+  return {
+    type: "flows",
+    label: `Flow: ${flow.name}`,
+    content: content || "(no artifacts)"
+  };
+}
+function buildSections(layers, mapping) {
+  const ownLayers = layers.filter((layer) => layer.type === "own");
+  if (mapping && mapping.length > 0) {
+    ownLayers.push({
+      type: "own",
+      label: "Materialization Target",
+      content: mapping.join(", ")
+    });
+  }
+  return [
+    { key: "Global", layers: layers.filter((l) => l.type === "global") },
+    { key: "Knowledge", layers: layers.filter((l) => l.type === "knowledge") },
+    { key: "Hierarchy", layers: layers.filter((l) => l.type === "hierarchy") },
+    { key: "OwnArtifacts", layers: ownLayers },
+    { key: "Dependencies", layers: layers.filter((l) => l.type === "relational") },
+    { key: "Aspects", layers: layers.filter((l) => l.type === "aspects") },
+    { key: "Flows", layers: layers.filter((l) => l.type === "flows") }
+  ];
+}
+function collectAncestors(node) {
+  const ancestors = [];
+  let current = node.parent;
+  while (current) {
+    ancestors.unshift(current);
+    current = current.parent;
+  }
+  return ancestors;
+}
+
+// src/core/validator.ts
+import { readdir as readdir4 } from "fs/promises";
+import path8 from "path";
+
+// src/utils/git.ts
+import { execSync } from "child_process";
+import path7 from "path";
+function getLastCommitTimestamp(projectRoot, relativePath) {
+  const normalized = path7.normalize(relativePath).replace(/\\/g, "/");
+  try {
+    const out = execSync(`git log -1 --format=%ct -- "${normalized}"`, {
+      cwd: projectRoot,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    const ts = parseInt(out.trim(), 10);
+    return Number.isNaN(ts) ? null : ts;
+  } catch {
+    return null;
+  }
+}
+
+// src/core/validator.ts
+var RESERVED_DIRS = /* @__PURE__ */ new Set();
+async function validate(graph, scope = "all") {
+  const issues = [];
+  if (graph.configError) {
+    issues.push({
+      severity: "error",
+      code: "E012",
+      rule: "invalid-config",
+      message: graph.configError
+    });
+  }
+  for (const { nodePath, message } of graph.nodeParseErrors ?? []) {
+    issues.push({
+      severity: "error",
+      code: "E001",
+      rule: "invalid-node-yaml",
+      message,
+      nodePath
+    });
+  }
+  if (!graph.configError) {
+    issues.push(...checkNodeTypes(graph));
+    issues.push(...checkTagsDefined(graph));
+    issues.push(...checkAspectTags(graph));
+    issues.push(...checkAspectTagUniqueness(graph));
+    issues.push(...checkRequiredArtifacts(graph));
+    issues.push(...await checkUnknownKnowledgeCategories(graph));
+    issues.push(...checkInvalidArtifactConditions(graph));
+    issues.push(...checkScopeTagsDefined(graph));
+    issues.push(...await checkMissingPatternExamples(graph));
+    issues.push(...await checkContextBudget(graph));
+    issues.push(...checkHighFanOut(graph));
+    issues.push(...await checkStaleKnowledge(graph));
+    issues.push(...checkTemplates(graph));
+  }
+  issues.push(...checkRelationTargets(graph));
+  issues.push(...checkNoCycles(graph));
+  issues.push(...checkMappingOverlap(graph));
+  issues.push(...checkBrokenKnowledgeRefs(graph));
+  issues.push(...checkBrokenFlowRefs(graph));
+  issues.push(...checkBrokenScopeRefs(graph));
+  issues.push(...await checkDirectoriesHaveNodeYaml(graph));
+  issues.push(...await checkShallowArtifacts(graph));
+  issues.push(...await checkUnreachableKnowledge(graph));
+  issues.push(...checkUnpairedEvents(graph));
+  let filtered = issues;
+  let nodesScanned = graph.nodes.size;
+  if (scope !== "all" && scope.trim()) {
+    if (!graph.nodes.has(scope)) {
+      return {
+        issues: [{ severity: "error", rule: "invalid-scope", message: `Node not found: ${scope}` }],
+        nodesScanned: 0
+      };
+    }
+    filtered = issues.filter((i) => !i.nodePath || i.nodePath === scope);
+    nodesScanned = 1;
+  }
+  return { issues: filtered, nodesScanned };
+}
+function checkNodeTypes(graph) {
+  const issues = [];
+  const allowedTypes = new Set(graph.config.node_types ?? []);
+  for (const [nodePath, node] of graph.nodes) {
+    if (!allowedTypes.has(node.meta.type)) {
+      issues.push({
+        severity: "error",
+        code: "E002",
+        rule: "unknown-node-type",
+        message: `Node type '${node.meta.type}' not in config.node_types (${[...allowedTypes].join(", ")})`,
+        nodePath
+      });
+    }
+  }
+  return issues;
+}
+function findSimilar(target, candidates) {
+  if (candidates.length === 0) return null;
+  let best = null;
+  let bestScore = -1;
+  for (const c of candidates) {
+    if (c === target) return c;
+    const targetParts = target.split("/");
+    const candParts = c.split("/");
+    let score = 0;
+    for (let i = 0; i < Math.min(targetParts.length, candParts.length); i++) {
+      if (targetParts[i] === candParts[i]) score++;
+      else break;
+    }
+    if (score > bestScore && score > 0) {
+      bestScore = score;
+      best = c;
+    }
+  }
+  return best;
+}
+function checkRelationTargets(graph) {
+  const issues = [];
+  const nodePaths = [...graph.nodes.keys()];
+  for (const [nodePath, node] of graph.nodes) {
+    for (const rel of node.meta.relations ?? []) {
+      if (!graph.nodes.has(rel.target)) {
+        const suggestion = findSimilar(rel.target, nodePaths);
+        const parts = rel.target.split("/");
+        const parentPrefix = parts.length > 1 ? parts.slice(0, -1).join("/") + "/" : "";
+        const existingInParent = nodePaths.filter((p) => p.startsWith(parentPrefix) && p !== rel.target).map((p) => {
+          const rest = p.slice(parentPrefix.length);
+          return rest.split("/")[0];
+        }).filter((v, i, a) => a.indexOf(v) === i).sort();
+        const existingLine = existingInParent.length > 0 ? `
+     Existing nodes in ${parentPrefix || "model/"}: ${existingInParent.join(", ")}` : "";
+        const hint = suggestion ? `
+     Did you mean '${suggestion}'?` : "";
+        issues.push({
+          severity: "error",
+          code: "E004",
+          rule: "broken-relation",
+          message: `Relation target '${rel.target}' does not exist${existingLine}${hint}`,
+          nodePath
+        });
+      }
+    }
+  }
+  return issues;
+}
+function checkTagsDefined(graph) {
+  const issues = [];
+  const definedTags = new Set(graph.config.tags ?? []);
+  for (const [nodePath, node] of graph.nodes) {
+    for (const tag of node.meta.tags ?? []) {
+      if (!definedTags.has(tag)) {
+        issues.push({
+          severity: "error",
+          code: "E003",
+          rule: "unknown-tag",
+          message: `Tag '${tag}' not defined in config.yaml`,
+          nodePath
+        });
+      }
+    }
+  }
+  return issues;
+}
+function checkAspectTags(graph) {
+  const issues = [];
+  const definedTags = new Set(graph.config.tags ?? []);
+  for (const aspect of graph.aspects) {
+    if (!definedTags.has(aspect.tag)) {
+      issues.push({
+        severity: "error",
+        code: "E007",
+        rule: "broken-aspect-tag",
+        message: `Aspect '${aspect.name}' references undefined tag '${aspect.tag}'`
+      });
+    }
+  }
+  return issues;
+}
+function checkAspectTagUniqueness(graph) {
+  const issues = [];
+  const byTag = /* @__PURE__ */ new Map();
+  for (const aspect of graph.aspects) {
+    const names = byTag.get(aspect.tag) ?? [];
+    names.push(aspect.name);
+    byTag.set(aspect.tag, names);
+  }
+  for (const [tag, names] of byTag) {
+    if (names.length <= 1) continue;
+    issues.push({
+      severity: "error",
+      code: "E014",
+      rule: "duplicate-aspect-binding",
+      message: `Tag '${tag}' is bound to multiple aspects (${names.join(", ")})`
+    });
+  }
+  return issues;
+}
+function checkNoCycles(graph) {
+  const WHITE = 0;
+  const GRAY = 1;
+  const BLACK = 2;
+  const color = /* @__PURE__ */ new Map();
+  for (const p of graph.nodes.keys()) color.set(p, WHITE);
+  const issues = [];
+  function dfs(nodePath, pathSegments) {
+    color.set(nodePath, GRAY);
+    const node = graph.nodes.get(nodePath);
+    const structuralTypes = /* @__PURE__ */ new Set(["uses", "calls", "extends", "implements"]);
+    for (const rel of node.meta.relations ?? []) {
+      const targetNode = graph.nodes.get(rel.target);
+      if (!targetNode) continue;
+      if (!structuralTypes.has(rel.type)) continue;
+      if (color.get(rel.target) === GRAY) {
+        const cyclePath = [...pathSegments, nodePath, rel.target];
+        const cycleNodes = pathSegments.slice(pathSegments.indexOf(rel.target)).concat(nodePath);
+        const hasBlackboxInCycle = cycleNodes.some(
+          (p) => graph.nodes.get(p)?.meta.blackbox === true
+        );
+        if (!hasBlackboxInCycle) {
+          issues.push({
+            severity: "error",
+            code: "E010",
+            rule: "structural-cycle",
+            message: `Circular dependency: ${cyclePath.join(" -> ")}`
+          });
+        }
+        return true;
+      }
+      if (color.get(rel.target) === WHITE) {
+        if (dfs(rel.target, [...pathSegments, nodePath])) return true;
+      }
+    }
+    color.set(nodePath, BLACK);
+    return false;
+  }
+  for (const nodePath of graph.nodes.keys()) {
+    if (color.get(nodePath) === WHITE) {
+      dfs(nodePath, []);
+    }
+  }
+  return issues;
+}
+function normalizePathForCompare(mappingPath) {
+  return mappingPath.replace(/\\/g, "/").replace(/\/+$/, "");
+}
+function arePathsOverlapping(pathA, pathB) {
+  if (pathA === pathB) return true;
+  return pathA.startsWith(pathB + "/") || pathB.startsWith(pathA + "/");
+}
+function checkMappingOverlap(graph) {
+  const issues = [];
+  const ownership = [];
+  for (const [nodePath, node] of graph.nodes) {
+    const mappingPaths = normalizeMappingPaths(node.meta.mapping).map(normalizePathForCompare).filter((mappingPath) => mappingPath.length > 0);
+    for (const mappingPath of mappingPaths) {
+      ownership.push({ nodePath, mappingPath });
+    }
+  }
+  for (let index = 0; index < ownership.length; index++) {
+    const current = ownership[index];
+    for (let nestedIndex = index + 1; nestedIndex < ownership.length; nestedIndex++) {
+      const candidate = ownership[nestedIndex];
+      if (current.nodePath === candidate.nodePath) continue;
+      if (!arePathsOverlapping(current.mappingPath, candidate.mappingPath)) continue;
+      issues.push({
+        severity: "error",
+        code: "E009",
+        rule: "overlapping-mapping",
+        message: `Mapping paths '${current.mappingPath}' (${current.nodePath}) and '${candidate.mappingPath}' (${candidate.nodePath}) overlap. Keep one owner mapping and model other concerns via relations.`,
+        nodePath: candidate.nodePath
+      });
+    }
+  }
+  return issues;
+}
+function getIncomingRelationSources(graph, nodePath) {
+  const sources = [];
+  for (const [srcPath, node] of graph.nodes) {
+    for (const rel of node.meta.relations ?? []) {
+      if (rel.target === nodePath) sources.push(srcPath);
+    }
+  }
+  return sources;
+}
+function artifactRequiredReason(graph, nodePath, node, required) {
+  if (required === "never") return null;
+  if (required === "always") {
+    return node.meta.blackbox ? null : "required: always";
+  }
+  const when = required.when;
+  if (when === "has_incoming_relations") {
+    const sources = getIncomingRelationSources(graph, nodePath);
+    return sources.length > 0 ? `${sources.length} incoming relation(s): ${sources.join(", ")}` : null;
+  }
+  if (when === "has_outgoing_relations") {
+    const count = node.meta.relations?.length ?? 0;
+    return count > 0 ? `${count} outgoing relation(s)` : null;
+  }
+  if (when.startsWith("has_tag:")) {
+    const tag = when.slice(8);
+    return (node.meta.tags ?? []).includes(tag) ? `node has tag '${tag}'` : null;
+  }
+  return null;
+}
+function getIncomingRelations(graph, nodePath) {
+  const incoming = [];
+  for (const [fromPath, node] of graph.nodes) {
+    for (const rel of node.meta.relations ?? []) {
+      if (rel.target === nodePath) {
+        incoming.push(fromPath);
+        break;
+      }
+    }
+  }
+  return incoming.sort();
+}
+function checkRequiredArtifacts(graph) {
+  const issues = [];
+  const artifacts = graph.config.artifacts ?? {};
+  for (const [nodePath, node] of graph.nodes) {
+    for (const [filename, config] of Object.entries(artifacts)) {
+      const hasArtifact = node.artifacts.some((a) => a.filename === filename);
+      const reason = artifactRequiredReason(graph, nodePath, node, config.required);
+      if (reason && !hasArtifact) {
+        const action = config.description ?? "";
+        const incoming = getIncomingRelations(graph, nodePath);
+        const incomingStr = incoming.length > 0 ? ` Node has ${incoming.length} incoming relation(s): ${incoming.slice(0, 5).join(", ")}${incoming.length > 5 ? "..." : ""}.` : "";
+        const msg = action ? `Missing required artifact '${filename}' (${reason}).${incomingStr} ${action}` : `Missing required artifact '${filename}' (${reason}).${incomingStr}`;
+        issues.push({
+          severity: "warning",
+          code: "W001",
+          rule: "missing-artifact",
+          message: msg.trim(),
+          nodePath
+        });
+      }
+    }
+  }
+  return issues;
+}
+function checkBrokenKnowledgeRefs(graph) {
+  const issues = [];
+  const knowledgePaths = new Set(graph.knowledge.map((k) => k.path));
+  for (const [nodePath, node] of graph.nodes) {
+    for (const kPath of node.meta.knowledge ?? []) {
+      const norm = kPath.replace(/\/$/, "");
+      if (!knowledgePaths.has(norm) && !knowledgePaths.has(kPath)) {
+        issues.push({
+          severity: "error",
+          code: "E005",
+          rule: "broken-knowledge-ref",
+          message: `Knowledge ref '${kPath}' does not resolve to existing knowledge item`,
+          nodePath
+        });
+      }
+    }
+  }
+  return issues;
+}
+function checkBrokenFlowRefs(graph) {
+  const issues = [];
+  const nodePaths = new Set(graph.nodes.keys());
+  const knowledgePaths = new Set(graph.knowledge.map((k) => k.path));
+  for (const flow of graph.flows) {
+    for (const n of flow.nodes) {
+      if (!nodePaths.has(n)) {
+        issues.push({
+          severity: "error",
+          code: "E006",
+          rule: "broken-flow-ref",
+          message: `Flow '${flow.name}' references non-existent node '${n}'`
+        });
+      }
+    }
+    for (const kPath of flow.knowledge ?? []) {
+      const norm = kPath.replace(/\/$/, "");
+      if (!knowledgePaths.has(norm) && !knowledgePaths.has(kPath)) {
+        issues.push({
+          severity: "error",
+          code: "E005",
+          rule: "broken-knowledge-ref",
+          message: `Flow '${flow.name}' references non-existent knowledge '${kPath}'`,
+          nodePath: `flows/${flow.name}`
+        });
+      }
+    }
+  }
+  return issues;
+}
+function checkBrokenScopeRefs(graph) {
+  const issues = [];
+  const nodePaths = new Set(graph.nodes.keys());
+  for (const k of graph.knowledge) {
+    if (typeof k.scope === "object" && "nodes" in k.scope) {
+      for (const n of k.scope.nodes) {
+        if (!nodePaths.has(n)) {
+          issues.push({
+            severity: "error",
+            code: "E008",
+            rule: "broken-scope-ref",
+            message: `Knowledge '${k.path}' scope references non-existent node '${n}'`
+          });
+        }
+      }
+    }
+  }
+  return issues;
+}
+function checkScopeTagsDefined(graph) {
+  const issues = [];
+  const definedTags = new Set(graph.config.tags ?? []);
+  for (const k of graph.knowledge) {
+    if (typeof k.scope !== "object" || !("tags" in k.scope)) continue;
+    for (const tag of k.scope.tags) {
+      if (definedTags.has(tag)) continue;
+      issues.push({
+        severity: "error",
+        code: "E008",
+        rule: "broken-scope-ref",
+        message: `Knowledge '${k.path}' scope references undefined tag '${tag}'`
+      });
+    }
+  }
+  return issues;
+}
+async function checkUnknownKnowledgeCategories(graph) {
+  const issues = [];
+  const categorySet = new Set((graph.config.knowledge_categories ?? []).map((c) => c.name));
+  const knowledgeDir = path8.join(graph.rootPath, "knowledge");
+  const existingDirs = /* @__PURE__ */ new Set();
+  try {
+    const entries = await readdir4(knowledgeDir, { withFileTypes: true });
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      if (e.name.startsWith(".")) continue;
+      existingDirs.add(e.name);
+      if (!categorySet.has(e.name)) {
+        issues.push({
+          severity: "error",
+          code: "E011",
+          rule: "unknown-knowledge-category",
+          message: `Directory knowledge/${e.name}/ does not match any config.knowledge_categories`
+        });
+      }
+    }
+  } catch {
+  }
+  for (const cat of graph.config.knowledge_categories ?? []) {
+    if (!existingDirs.has(cat.name)) {
+      issues.push({
+        severity: "error",
+        code: "E017",
+        rule: "missing-knowledge-category-dir",
+        message: `Category '${cat.name}' in config has no knowledge/${cat.name}/ directory`
+      });
+    }
+  }
+  return issues;
+}
+function checkInvalidArtifactConditions(graph) {
+  const issues = [];
+  const definedTags = new Set(graph.config.tags ?? []);
+  const artifacts = graph.config.artifacts ?? {};
+  for (const [artifactName, config] of Object.entries(artifacts)) {
+    const required = config.required;
+    if (typeof required === "object" && required && "when" in required) {
+      const when = required.when;
+      if (when.startsWith("has_tag:")) {
+        const tag = when.slice(8);
+        if (!definedTags.has(tag)) {
+          issues.push({
+            severity: "error",
+            code: "E013",
+            rule: "invalid-artifact-condition",
+            message: `Artifact '${artifactName}' condition has_tag:${tag} references undefined tag`
+          });
+        }
+      }
+    }
+  }
+  return issues;
+}
+async function checkShallowArtifacts(graph) {
+  const issues = [];
+  const minLen = graph.config.quality?.min_artifact_length ?? 50;
+  for (const [nodePath, node] of graph.nodes) {
+    for (const art of node.artifacts) {
+      if (art.content.trim().length < minLen) {
+        issues.push({
+          severity: "warning",
+          code: "W002",
+          rule: "shallow-artifact",
+          message: `Artifact '${art.filename}' is below minimum length (${art.content.length} < ${minLen})`,
+          nodePath
+        });
+      }
+    }
+  }
+  return issues;
+}
+async function checkUnreachableKnowledge(graph) {
+  const issues = [];
+  const nodePaths = new Set(graph.nodes.keys());
+  const nodeTags = /* @__PURE__ */ new Map();
+  for (const [p, n] of graph.nodes) {
+    nodeTags.set(p, new Set(n.meta.tags ?? []));
+  }
+  const knowledgeReachable = /* @__PURE__ */ new Set();
+  for (const k of graph.knowledge) {
+    if (k.scope === "global") {
+      knowledgeReachable.add(k.path);
+      continue;
+    }
+    if (typeof k.scope === "object" && "tags" in k.scope) {
+      for (const [, tags] of nodeTags) {
+        if (k.scope.tags.some((t) => tags.has(t))) {
+          knowledgeReachable.add(k.path);
+          break;
+        }
+      }
+    }
+    if (typeof k.scope === "object" && "nodes" in k.scope) {
+      if (k.scope.nodes.some((n) => nodePaths.has(n))) {
+        knowledgeReachable.add(k.path);
+      }
+    }
+  }
+  for (const [, node] of graph.nodes) {
+    for (const kPath of node.meta.knowledge ?? []) {
+      const k = graph.knowledge.find(
+        (i) => i.path === kPath || i.path === kPath.replace(/\/$/, "")
+      );
+      if (k) knowledgeReachable.add(k.path);
+    }
+  }
+  for (const flow of graph.flows) {
+    for (const kPath of flow.knowledge ?? []) {
+      const k = graph.knowledge.find(
+        (i) => i.path === kPath || i.path === kPath.replace(/\/$/, "")
+      );
+      if (k) knowledgeReachable.add(k.path);
+    }
+  }
+  for (const k of graph.knowledge) {
+    if (!knowledgeReachable.has(k.path)) {
+      issues.push({
+        severity: "warning",
+        code: "W003",
+        rule: "unreachable-knowledge",
+        message: `Knowledge '${k.path}' does not reach any context package`
+      });
+    }
+  }
+  return issues;
+}
+async function checkMissingPatternExamples(graph) {
+  const issues = [];
+  const hasPatterns = (graph.config.knowledge_categories ?? []).some((c) => c.name === "patterns");
+  if (!hasPatterns) return issues;
+  const patternsDir = path8.join(graph.rootPath, "knowledge", "patterns");
+  try {
+    const entries = await readdir4(patternsDir, { withFileTypes: true });
+    const exampleExtensions = /* @__PURE__ */ new Set([
+      ".ts",
+      ".js",
+      ".tsx",
+      ".jsx",
+      ".py",
+      ".go",
+      ".rs",
+      ".java",
+      ".kt"
+    ]);
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const itemDir = path8.join(patternsDir, e.name);
+      const itemEntries = await readdir4(itemDir, { withFileTypes: true });
+      const hasExample = itemEntries.some(
+        (f) => f.isFile() && f.name !== "knowledge.yaml" && (f.name.startsWith("example") || exampleExtensions.has(path8.extname(f.name).toLowerCase()))
+      );
+      if (!hasExample) {
+        issues.push({
+          severity: "warning",
+          code: "W004",
+          rule: "missing-example",
+          message: `Pattern 'patterns/${e.name}' has no example file`
+        });
+      }
+    }
+  } catch {
+  }
+  return issues;
+}
+function checkHighFanOut(graph) {
+  const issues = [];
+  const maxRel = graph.config.quality?.max_direct_relations ?? 10;
+  for (const [nodePath, node] of graph.nodes) {
+    const count = node.meta.relations?.length ?? 0;
+    if (count > maxRel) {
+      issues.push({
+        severity: "warning",
+        code: "W007",
+        rule: "high-fan-out",
+        message: `Node has ${count} direct relations (max: ${maxRel})`,
+        nodePath
+      });
+    }
+  }
+  return issues;
+}
+function getNodesInScope(k, graph) {
+  if (k.scope === "global") {
+    return [...graph.nodes.keys()];
+  }
+  if (typeof k.scope === "object" && "nodes" in k.scope && k.scope.nodes) {
+    return k.scope.nodes.filter((p) => graph.nodes.has(p));
+  }
+  if (typeof k.scope === "object" && "tags" in k.scope && k.scope.tags) {
+    const tagSet = new Set(k.scope.tags);
+    return [...graph.nodes.keys()].filter((p) => {
+      const node = graph.nodes.get(p);
+      return (node.meta.tags ?? []).some((t) => tagSet.has(t));
+    });
+  }
+  return [];
+}
+async function checkStaleKnowledge(graph) {
+  const issues = [];
+  const stalenessDays = graph.config.quality?.knowledge_staleness_days ?? 90;
+  const projectRoot = path8.dirname(graph.rootPath);
+  const yggRel = path8.relative(projectRoot, graph.rootPath).replace(/\\/g, "/") || ".yggdrasil";
+  for (const k of graph.knowledge) {
+    const scopeNodes = getNodesInScope(k, graph);
+    if (scopeNodes.length === 0) continue;
+    const kPath = `${yggRel}/knowledge/${k.path}`;
+    const tK = getLastCommitTimestamp(projectRoot, kPath);
+    if (tK === null) continue;
+    let maxTp = 0;
+    let latestNode = "";
+    for (const nodePath of scopeNodes) {
+      const nodePathRel = `${yggRel}/model/${nodePath}`;
+      const tP = getLastCommitTimestamp(projectRoot, nodePathRel);
+      if (tP !== null && tP > maxTp) {
+        maxTp = tP;
+        latestNode = nodePath;
+      }
+    }
+    if (maxTp === 0) continue;
+    const diffDays = (maxTp - tK) / (60 * 60 * 24);
+    if (diffDays > stalenessDays) {
+      issues.push({
+        severity: "warning",
+        code: "W008",
+        rule: "stale-knowledge",
+        message: `Knowledge '${k.path}' may be stale: node '${latestNode}' modified ${Math.floor(diffDays)} days later (Git commits)`,
+        nodePath: latestNode
+      });
+    }
+  }
+  return issues;
+}
+function checkUnpairedEvents(graph) {
+  const issues = [];
+  const emitsTo = /* @__PURE__ */ new Map();
+  const listensFrom = /* @__PURE__ */ new Map();
+  for (const [nodePath, node] of graph.nodes) {
+    for (const rel of node.meta.relations ?? []) {
+      if (rel.type === "emits") {
+        const set = emitsTo.get(nodePath) ?? /* @__PURE__ */ new Set();
+        set.add(rel.target);
+        emitsTo.set(nodePath, set);
+      }
+      if (rel.type === "listens") {
+        const set = listensFrom.get(nodePath) ?? /* @__PURE__ */ new Set();
+        set.add(rel.target);
+        listensFrom.set(nodePath, set);
+      }
+    }
+  }
+  for (const [emitter, targets] of emitsTo) {
+    for (const target of targets) {
+      const listenerSet = listensFrom.get(target);
+      if (!listenerSet?.has(emitter)) {
+        issues.push({
+          severity: "warning",
+          code: "W009",
+          rule: "unpaired-event",
+          message: `Node '${emitter}' emits to '${target}' but '${target}' has no listens from '${emitter}'`,
+          nodePath: emitter
+        });
+      }
+    }
+  }
+  for (const [listener, sources] of listensFrom) {
+    for (const source of sources) {
+      const emitterSet = emitsTo.get(source);
+      if (!emitterSet?.has(listener)) {
+        issues.push({
+          severity: "warning",
+          code: "W009",
+          rule: "unpaired-event",
+          message: `Node '${listener}' listens from '${source}' but '${source}' has no emits to '${listener}'`,
+          nodePath: listener
+        });
+      }
+    }
+  }
+  return issues;
+}
+function checkTemplates(graph) {
+  const issues = [];
+  const allowedTypes = new Set(graph.config.node_types ?? []);
+  const allowedArtifacts = new Set(Object.keys(graph.config.artifacts ?? {}));
+  const typeToTemplate = /* @__PURE__ */ new Map();
+  for (const template of graph.templates) {
+    if (!allowedTypes.has(template.nodeType)) {
+      issues.push({
+        severity: "error",
+        code: "E002",
+        rule: "unknown-node-type",
+        message: `Template for '${template.nodeType}' references node_type not in config.node_types (${[...allowedTypes].join(", ")})`
+      });
+    }
+    for (const artifact of template.suggestedArtifacts ?? []) {
+      if (!allowedArtifacts.has(artifact)) {
+        issues.push({
+          severity: "warning",
+          code: "W001",
+          rule: "missing-artifact",
+          message: `Template for '${template.nodeType}' suggests artifact '${artifact}' not defined in config.artifacts`
+        });
+      }
+    }
+    const existing = typeToTemplate.get(template.nodeType);
+    if (existing) {
+      issues.push({
+        severity: "error",
+        code: "E016",
+        rule: "duplicate-template",
+        message: `Multiple templates for node_type '${template.nodeType}'`
+      });
+    } else {
+      typeToTemplate.set(template.nodeType, template.nodeType);
+    }
+  }
+  return issues;
+}
+async function checkDirectoriesHaveNodeYaml(graph) {
+  const issues = [];
+  const modelDir = path8.join(graph.rootPath, "model");
+  async function scanDir(dirPath, segments) {
+    const entries = await readdir4(dirPath, { withFileTypes: true });
+    const hasNodeYaml = entries.some((e) => e.isFile() && e.name === "node.yaml");
+    const dirName = path8.basename(dirPath);
+    if (RESERVED_DIRS.has(dirName)) return;
+    const hasContent = entries.some((e) => e.isFile()) || entries.some((e) => e.isDirectory());
+    const graphPath = segments.join("/");
+    if (hasContent && !hasNodeYaml && graphPath !== "") {
+      issues.push({
+        severity: "error",
+        code: "E015",
+        rule: "missing-node-yaml",
+        message: `Directory '${graphPath}' has content but no node.yaml`,
+        nodePath: graphPath
+      });
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (RESERVED_DIRS.has(entry.name)) continue;
+      if (entry.name.startsWith(".")) continue;
+      await scanDir(path8.join(dirPath, entry.name), [...segments, entry.name]);
+    }
+  }
+  try {
+    const rootEntries = await readdir4(modelDir, { withFileTypes: true });
+    for (const entry of rootEntries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith(".")) continue;
+      await scanDir(path8.join(modelDir, entry.name), [entry.name]);
+    }
+  } catch {
+  }
+  return issues;
+}
+async function checkContextBudget(graph) {
+  const issues = [];
+  const warningThreshold = graph.config.quality?.context_budget.warning ?? 5e3;
+  const errorThreshold = graph.config.quality?.context_budget.error ?? 1e4;
+  for (const [nodePath, node] of graph.nodes) {
+    if (node.meta.blackbox) continue;
+    try {
+      const pkg = await buildContext(graph, nodePath);
+      if (pkg.tokenCount >= errorThreshold) {
+        issues.push({
+          severity: "warning",
+          code: "W006",
+          rule: "budget-error",
+          message: `Context is ${pkg.tokenCount.toLocaleString()} tokens (error threshold: ${errorThreshold.toLocaleString()}) \u2014 blocks materialization, node must be split`,
+          nodePath
+        });
+      } else if (pkg.tokenCount >= warningThreshold) {
+        issues.push({
+          severity: "warning",
+          code: "W005",
+          rule: "budget-warning",
+          message: `Context is ${pkg.tokenCount.toLocaleString()} tokens (warning threshold: ${warningThreshold.toLocaleString()}). Consider splitting the node or reducing dependencies.`,
+          nodePath
+        });
+      }
+    } catch {
+    }
+  }
+  return issues;
+}
+
+// src/formatters/markdown.ts
+function formatContextMarkdown(pkg) {
+  let md = "";
+  md += `# Context Package: ${pkg.nodeName}
+`;
+  md += `# Path: ${pkg.nodePath}
+`;
+  md += `# Generated: ${(/* @__PURE__ */ new Date()).toISOString()}
+
+`;
+  md += `---
+
+`;
+  for (const section of pkg.sections) {
+    if (section.layers.length === 0) continue;
+    md += `## ${section.key}
+
+`;
+    for (const layer of section.layers) {
+      md += `### ${layer.label}
+
+`;
+      md += layer.content;
+      md += `
+
+`;
+    }
+    md += `---
+
+`;
+  }
+  md += `Context size: ${pkg.tokenCount.toLocaleString()} tokens
+`;
+  md += `Layers: ${pkg.layers.map((l) => l.type).join(", ")}
+`;
+  return md;
+}
+
+// src/cli/build-context.ts
+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) => {
+    try {
+      const graph = await loadGraph(process.cwd());
+      const validationResult = await validate(graph, "all");
+      const structuralErrors = validationResult.issues.filter(
+        (issue) => issue.severity === "error"
+      );
+      if (structuralErrors.length > 0) {
+        process.stderr.write(
+          `Error: build-context requires a structurally valid graph (${structuralErrors.length} errors found).
+`
+        );
+        process.exit(1);
+      }
+      const nodePath = options.node.trim().replace(/\/$/, "");
+      const pkg = await buildContext(graph, nodePath);
+      const warningThreshold = graph.config.quality?.context_budget.warning ?? 5e3;
+      const errorThreshold = graph.config.quality?.context_budget.error ?? 1e4;
+      const budgetStatus = pkg.tokenCount >= errorThreshold ? "error" : pkg.tokenCount >= warningThreshold ? "warning" : "ok";
+      let output = formatContextMarkdown(pkg);
+      output += `Budget status: ${budgetStatus}
+`;
+      process.stdout.write(output);
+      if (budgetStatus === "error") {
+        process.stderr.write(
+          `Error: context package exceeds error budget (${pkg.tokenCount} >= ${errorThreshold}).
+`
+        );
+        process.exit(1);
+      }
+    } catch (error) {
+      process.stderr.write(`Error: ${error.message}
+`);
+      process.exit(1);
+    }
+  });
+}
+
+// src/cli/validate.ts
+import chalk from "chalk";
+function registerValidateCommand(program2) {
+  program2.command("validate").description("Validate graph structural integrity and completeness signals").option("--scope <scope>", "Scope: all or node-path (default: all)", "all").action(async (options) => {
+    try {
+      const graph = await loadGraph(process.cwd(), { tolerateInvalidConfig: true });
+      const scope = (options.scope ?? "all").trim() || "all";
+      const result = await validate(graph, scope);
+      process.stdout.write(`${result.nodesScanned} nodes scanned
+
+`);
+      const errors = result.issues.filter((i) => i.severity === "error");
+      const warnings = result.issues.filter((i) => i.severity === "warning");
+      for (const issue of errors) {
+        const code = issue.code ?? "";
+        const loc = issue.nodePath ?? "";
+        const prefix = loc ? `${code} ${loc} -> ` : `${code} `;
+        process.stdout.write(chalk.red(`\u2717 ${prefix}${issue.message}
+`));
+      }
+      for (const issue of warnings) {
+        const code = issue.code ?? "";
+        const loc = issue.nodePath ?? "";
+        const prefix = loc ? `${code} ${loc} -> ` : `${code} `;
+        process.stdout.write(chalk.yellow(`\u26A0 ${prefix}${issue.message}
+`));
+      }
+      if (errors.length === 0 && warnings.length === 0) {
+        process.stdout.write(chalk.green("\u2713 No issues found.\n"));
+      } else {
+        process.stdout.write(`
+${errors.length} errors, ${warnings.length} warnings.
+`);
+      }
+      const hasErrors = result.issues.some((i) => i.severity === "error");
+      process.exit(hasErrors ? 1 : 0);
+    } catch (error) {
+      process.stderr.write(`Error: ${error.message}
+`);
+      process.exit(1);
+    }
+  });
+}
+
+// src/cli/drift.ts
+import chalk2 from "chalk";
+
+// src/io/drift-state-store.ts
+import { readFile as readFile11, writeFile as writeFile3 } from "fs/promises";
+import { parse as parseYaml7, stringify as stringifyYaml } from "yaml";
+import path9 from "path";
+var DRIFT_STATE_FILE = ".drift-state";
+function getCanonicalHash(entry) {
+  return typeof entry === "string" ? entry : entry.hash;
+}
+function getFileHashes(entry) {
+  return typeof entry === "object" ? entry.files : void 0;
+}
+async function readDriftState(yggRoot) {
+  const filePath = path9.join(yggRoot, DRIFT_STATE_FILE);
+  try {
+    const content = await readFile11(filePath, "utf-8");
+    const raw = parseYaml7(content);
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+      const result = {};
+      for (const [k, v] of Object.entries(raw)) {
+        if (typeof k === "string" && typeof v === "string") {
+          result[k] = v;
+        } else if (typeof k === "string" && typeof v === "object" && v !== null && "hash" in v) {
+          result[k] = v;
+        }
+      }
+      return result;
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}
+async function writeDriftState(yggRoot, state) {
+  const filePath = path9.join(yggRoot, DRIFT_STATE_FILE);
+  const content = stringifyYaml(state);
+  await writeFile3(filePath, content, "utf-8");
+}
+
+// src/utils/hash.ts
+import { readFile as readFile12, readdir as readdir5, stat as stat3 } from "fs/promises";
+import path10 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 readFile12(filePath);
+  return createHash("sha256").update(content).digest("hex");
+}
+async function hashPath(targetPath, options = {}) {
+  const projectRoot = options.projectRoot ? path10.resolve(options.projectRoot) : void 0;
+  const gitignoreMatcher = await loadGitignoreMatcher(projectRoot);
+  const targetStat = await stat3(targetPath);
+  if (targetStat.isFile()) {
+    if (isIgnoredPath(targetPath, projectRoot, gitignoreMatcher)) {
+      return hashString("");
+    }
+    return hashFile(targetPath);
+  }
+  if (targetStat.isDirectory()) {
+    const fileHashes = await collectDirectoryFileHashes(targetPath, targetPath, {
+      projectRoot,
+      gitignoreMatcher
+    });
+    const digestInput = fileHashes.sort((a, b) => a.path.localeCompare(b.path)).map((entry) => `${entry.path}:${entry.hash}`).join("\n");
+    return hashString(digestInput);
+  }
+  throw new Error(`Unsupported mapping path type: ${targetPath}`);
+}
+async function collectDirectoryFileHashes(directoryPath, rootDirectoryPath, options) {
+  const entries = await readdir5(directoryPath, { withFileTypes: true });
+  const result = [];
+  for (const entry of entries) {
+    const absoluteChildPath = path10.join(directoryPath, entry.name);
+    if (isIgnoredPath(absoluteChildPath, options.projectRoot, options.gitignoreMatcher)) {
+      continue;
+    }
+    if (entry.isDirectory()) {
+      const nested = await collectDirectoryFileHashes(
+        absoluteChildPath,
+        rootDirectoryPath,
+        options
+      );
+      for (const nestedEntry of nested) {
+        result.push({
+          path: path10.relative(rootDirectoryPath, path10.join(absoluteChildPath, nestedEntry.path)),
+          hash: nestedEntry.hash
+        });
+      }
+      continue;
+    }
+    if (!entry.isFile()) {
+      continue;
+    }
+    result.push({
+      path: path10.relative(rootDirectoryPath, absoluteChildPath),
+      hash: await hashFile(absoluteChildPath)
+    });
+  }
+  return result;
+}
+async function loadGitignoreMatcher(projectRoot) {
+  if (!projectRoot) {
+    return void 0;
+  }
+  try {
+    const gitignorePath = path10.join(projectRoot, ".gitignore");
+    const gitignoreContent = await readFile12(gitignorePath, "utf-8");
+    const matcher = ignoreFactory();
+    matcher.add(gitignoreContent);
+    return matcher;
+  } catch {
+    return void 0;
+  }
+}
+function isIgnoredPath(candidatePath, projectRoot, matcher) {
+  if (!projectRoot || !matcher) {
+    return false;
+  }
+  const relativePath = path10.relative(projectRoot, candidatePath);
+  if (relativePath === "" || relativePath.startsWith("..")) {
+    return false;
+  }
+  return matcher.ignores(relativePath) || matcher.ignores(relativePath + "/");
+}
+function hashString(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+async function perFileHashes(projectRoot, mapping) {
+  const root = path10.resolve(projectRoot);
+  const paths = mapping.paths ?? [];
+  if (paths.length === 0) return [];
+  const result = [];
+  const gitignoreMatcher = await loadGitignoreMatcher(root);
+  for (const p of paths) {
+    const absPath = path10.join(root, p);
+    const st = await stat3(absPath);
+    if (st.isFile()) {
+      result.push({ path: p, hash: await hashFile(absPath) });
+    } else if (st.isDirectory()) {
+      const hashes = await collectDirectoryFileHashes(absPath, absPath, {
+        projectRoot: root,
+        gitignoreMatcher
+      });
+      for (const h of hashes) {
+        result.push({
+          path: path10.join(p, h.path).split(path10.sep).join("/"),
+          hash: h.hash
+        });
+      }
+    }
+  }
+  return result;
+}
+async function hashForMapping(projectRoot, mapping) {
+  const root = path10.resolve(projectRoot);
+  const paths = mapping.paths ?? [];
+  if (paths.length === 0) throw new Error("Invalid mapping for hash: no paths");
+  const pairs = [];
+  for (const p of paths) {
+    const absPath = path10.join(root, p);
+    const st = await stat3(absPath);
+    if (st.isFile()) {
+      pairs.push({ path: p, hash: await hashFile(absPath) });
+    } else if (st.isDirectory()) {
+      const dirHash = await hashPath(absPath, { projectRoot: root });
+      pairs.push({ path: p, hash: dirHash });
+    }
+  }
+  const digestInput = pairs.sort((a, b) => a.path.localeCompare(b.path)).map((e) => `${e.path}:${e.hash}`).join("\n");
+  return createHash("sha256").update(digestInput).digest("hex");
+}
+
+// src/core/drift-detector.ts
+import { access } from "fs/promises";
+import path11 from "path";
+async function detectDrift(graph, filterNodePath) {
+  const projectRoot = path11.dirname(graph.rootPath);
+  const driftState = await readDriftState(graph.rootPath);
+  const entries = [];
+  for (const [nodePath, node] of graph.nodes) {
+    if (filterNodePath && nodePath !== filterNodePath) continue;
+    const mapping = node.meta.mapping;
+    if (!mapping) continue;
+    const mappingPaths = normalizeMappingPaths(mapping);
+    if (mappingPaths.length === 0) continue;
+    const storedEntry = driftState[nodePath];
+    if (!storedEntry) {
+      const allMissing = await allPathsMissing(projectRoot, mappingPaths);
+      entries.push({
+        nodePath,
+        mappingPaths,
+        status: allMissing ? "unmaterialized" : "drift",
+        details: allMissing ? "No drift state recorded, files do not exist" : "No drift state recorded, files exist (run drift-sync after materialization)"
+      });
+      continue;
+    }
+    const storedHash = getCanonicalHash(storedEntry);
+    let status = "ok";
+    let details = "";
+    try {
+      const currentHash = await hashForMapping(projectRoot, mapping);
+      if (currentHash !== storedHash) {
+        status = "drift";
+        const changedFiles = await diagnoseChangedFiles(
+          projectRoot,
+          mapping,
+          getFileHashes(storedEntry)
+        );
+        details = changedFiles.length > 0 ? `Changed files: ${changedFiles.join(", ")}` : "File(s) modified since last sync";
+      }
+    } catch {
+      status = "missing";
+      details = "Mapped path(s) do not exist";
+    }
+    entries.push({ nodePath, mappingPaths, status, details });
+  }
+  return {
+    entries,
+    totalChecked: entries.length,
+    okCount: entries.filter((e) => e.status === "ok").length,
+    driftCount: entries.filter((e) => e.status === "drift").length,
+    missingCount: entries.filter((e) => e.status === "missing").length,
+    unmaterializedCount: entries.filter((e) => e.status === "unmaterialized").length
+  };
+}
+async function diagnoseChangedFiles(projectRoot, mapping, storedFileHashes) {
+  try {
+    const currentHashes = await perFileHashes(projectRoot, mapping);
+    if (!storedFileHashes) {
+      return currentHashes.map((h) => h.path).sort();
+    }
+    const changed = [];
+    const storedPaths = new Set(Object.keys(storedFileHashes));
+    for (const { path: filePath, hash } of currentHashes) {
+      const stored = storedFileHashes[filePath];
+      if (!stored || stored !== hash) {
+        changed.push(filePath);
+      }
+      storedPaths.delete(filePath);
+    }
+    for (const removed of storedPaths) {
+      changed.push(`${removed} (deleted)`);
+    }
+    return changed.sort();
+  } catch {
+    return [];
+  }
+}
+async function allPathsMissing(projectRoot, mappingPaths) {
+  for (const mp of mappingPaths) {
+    const absPath = path11.join(projectRoot, mp);
+    try {
+      await access(absPath);
+      return false;
+    } catch {
+    }
+  }
+  return true;
+}
+async function syncDriftState(graph, nodePath) {
+  const projectRoot = path11.dirname(graph.rootPath);
+  const node = graph.nodes.get(nodePath);
+  if (!node) throw new Error(`Node not found: ${nodePath}`);
+  const mapping = node.meta.mapping;
+  if (!mapping) throw new Error(`Node has no mapping: ${nodePath}`);
+  const currentHash = await hashForMapping(projectRoot, mapping);
+  const driftState = await readDriftState(graph.rootPath);
+  const previousEntry = driftState[nodePath];
+  const previousHash = previousEntry ? getCanonicalHash(previousEntry) : void 0;
+  const fileHashes = await perFileHashes(projectRoot, mapping);
+  const files = {};
+  for (const fh of fileHashes) {
+    files[fh.path] = fh.hash;
+  }
+  const newEntry = { hash: currentHash, files };
+  driftState[nodePath] = newEntry;
+  await writeDriftState(graph.rootPath, driftState);
+  return { previousHash, currentHash };
+}
+
+// src/cli/drift.ts
+function registerDriftCommand(program2) {
+  program2.command("drift").description("Detect divergence between graph and code").option("--scope <scope>", "Scope: all or node-path (default: all)", "all").action(async (options) => {
+    try {
+      const graph = await loadGraph(process.cwd());
+      const scope = (options.scope ?? "all").trim() || "all";
+      if (scope && scope !== "all" && !graph.nodes.has(scope)) {
+        process.stderr.write(`Error: Node not found: ${scope}
+`);
+        process.exit(1);
+      }
+      if (scope && scope !== "all") {
+        const scopedNode = graph.nodes.get(scope);
+        if (!scopedNode.meta.mapping) {
+          process.stderr.write(
+            `Error: Node has no mapping (does not participate in drift detection): ${options.scope}
+`
+          );
+          process.exit(1);
+        }
+      }
+      const scopeNode = scope === "all" ? void 0 : scope;
+      const report = await detectDrift(graph, scopeNode);
+      process.stdout.write("Drift:\n");
+      for (const entry of report.entries) {
+        const paths = entry.mappingPaths.join(", ");
+        switch (entry.status) {
+          case "ok":
+            process.stdout.write(chalk2.green(`  ok       ${entry.nodePath} -> ${paths}
+`));
+            break;
+          case "drift":
+            process.stdout.write(chalk2.red(`  drift    ${entry.nodePath} -> ${paths}
+`));
+            if (entry.details) process.stdout.write(`           ${entry.details}
+`);
+            break;
+          case "missing":
+            process.stdout.write(chalk2.yellow(`  missing  ${entry.nodePath} -> ${paths}
+`));
+            break;
+          case "unmaterialized":
+            process.stdout.write(chalk2.dim(`  unmat.   ${entry.nodePath} -> ${paths}
+`));
+            break;
+        }
+      }
+      process.stdout.write(
+        `
+Summary: ${report.driftCount} drift, ${report.missingCount} missing, ${report.unmaterializedCount} unmaterialized, ${report.okCount} ok
+`
+      );
+      if (report.driftCount > 0 || report.missingCount > 0 || report.unmaterializedCount > 0) {
+        process.exit(1);
+      }
+      process.exit(0);
+    } catch (error) {
+      process.stderr.write(`Error: ${error.message}
+`);
+      process.exit(1);
+    }
+  });
+}
+
+// src/cli/drift-sync.ts
+import chalk3 from "chalk";
+function registerDriftSyncCommand(program2) {
+  program2.command("drift-sync").description("Record current file hash after resolving drift").requiredOption("--node <path>", "Node path to sync").action(async (options) => {
+    try {
+      const graph = await loadGraph(process.cwd());
+      const nodePath = options.node.trim().replace(/\/$/, "");
+      const { previousHash, currentHash } = await syncDriftState(graph, nodePath);
+      process.stdout.write(chalk3.green(`Synchronized: ${nodePath}
+`));
+      process.stdout.write(
+        `  Hash: ${previousHash ? previousHash.slice(0, 8) : "none"} -> ${currentHash.slice(0, 8)}
+`
+      );
+    } catch (error) {
+      process.stderr.write(`Error: ${error.message}
+`);
+      process.exit(1);
+    }
+  });
+}
+
+// src/cli/status.ts
+function registerStatusCommand(program2) {
+  program2.command("status").description("Show graph summary").action(async () => {
+    try {
+      const graph = await loadGraph(process.cwd());
+      const typeCounts = /* @__PURE__ */ new Map();
+      let blackboxCount = 0;
+      for (const node of graph.nodes.values()) {
+        typeCounts.set(node.meta.type, (typeCounts.get(node.meta.type) ?? 0) + 1);
+        if (node.meta.blackbox) blackboxCount++;
+      }
+      let structuralRelations = 0;
+      let eventRelations = 0;
+      const structuralTypes = /* @__PURE__ */ new Set(["uses", "calls", "extends", "implements"]);
+      for (const node of graph.nodes.values()) {
+        for (const rel of node.meta.relations ?? []) {
+          if (structuralTypes.has(rel.type)) structuralRelations += 1;
+          else eventRelations += 1;
+        }
+      }
+      const flowCount = graph.flows.length;
+      const knowledgeCount = graph.knowledge.length;
+      const drift = await detectDrift(graph);
+      const validation = await validate(graph, "all");
+      const errorCount = validation.issues.filter((issue) => issue.severity === "error").length;
+      const warningCount = validation.issues.filter(
+        (issue) => issue.severity === "warning"
+      ).length;
+      process.stdout.write(`Graph: ${graph.config.name}
+`);
+      const pluralize = (word, count) => count === 1 ? word : word.endsWith("y") ? word.slice(0, -1) + "ies" : word + "s";
+      const typeStr = [...typeCounts.entries()].map(([t, c]) => `${c} ${pluralize(t, c)}`).join(", ");
+      process.stdout.write(
+        `Nodes: ${graph.nodes.size} (${typeStr}) + ${blackboxCount} blackbox
+`
+      );
+      process.stdout.write(
+        `Relations: ${structuralRelations} structural, ${eventRelations} event
+`
+      );
+      process.stdout.write(
+        `Aspects: ${graph.aspects.length}    Flows: ${flowCount}    Knowledge: ${knowledgeCount}
+`
+      );
+      process.stdout.write(
+        `Drift: ${drift.driftCount} drift, ${drift.missingCount} missing, ${drift.unmaterializedCount} unmaterialized, ${drift.okCount} ok
+`
+      );
+      process.stdout.write(`Validation: ${errorCount} errors, ${warningCount} warnings
+`);
+    } catch (error) {
+      process.stderr.write(`Error: ${error.message}
+`);
+      process.exit(1);
+    }
+  });
+}
+
+// src/cli/tree.ts
+function registerTreeCommand(program2) {
+  program2.command("tree").description("Display graph structure as a tree").option("--root <path>", "Show only subtree rooted at this path").option("--depth <n>", "Maximum depth", (v) => parseInt(v, 10)).action(async (options) => {
+    try {
+      const graph = await loadGraph(process.cwd());
+      let roots;
+      let showProjectName;
+      if (options.root?.trim()) {
+        const path15 = options.root.trim().replace(/\/$/, "");
+        const node = graph.nodes.get(path15);
+        if (!node) {
+          process.stderr.write(`Error: path '${path15}' not found
+`);
+          process.exit(1);
+        }
+        roots = [node];
+        showProjectName = false;
+      } else {
+        roots = [...graph.nodes.values()].filter((n) => n.parent === null).sort((a, b) => a.path.localeCompare(b.path));
+        showProjectName = true;
+      }
+      if (showProjectName) {
+        process.stdout.write("model/\n");
+      }
+      for (let i = 0; i < roots.length; i++) {
+        const isLast = i === roots.length - 1;
+        printNode(roots[i], "", isLast, 1, options.depth);
+      }
+    } catch (error) {
+      process.stderr.write(`Error: ${error.message}
+`);
+      process.exit(1);
+    }
+  });
+}
+function printNode(node, prefix, isLast, depth, maxDepth) {
+  const connector = isLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
+  const name = node.path.split("/").pop() ?? node.path;
+  const type = `[${node.meta.type}]`;
+  const tags = node.meta.tags?.length ? ` tags:${node.meta.tags.join(",")}` : "";
+  const blackbox = node.meta.blackbox ? " \u25A0 blackbox" : "";
+  const relationCount = node.meta.relations?.length ?? 0;
+  process.stdout.write(
+    `${prefix}${connector}${name}/ ${type}${tags}${blackbox} -> ${relationCount} relations
+`
+  );
+  const childPrefix = prefix + (isLast ? "    " : "\u2502   ");
+  if (maxDepth !== void 0 && depth >= maxDepth) return;
+  const children = [...node.children].sort((a, b) => a.path.localeCompare(b.path));
+  for (let i = 0; i < children.length; i++) {
+    printNode(children[i], childPrefix, i === children.length - 1, depth + 1, maxDepth);
+  }
+}
+
+// src/cli/owner.ts
+function normalizeForMatch(inputPath) {
+  return inputPath.replace(/\\/g, "/").replace(/\/+$/, "");
+}
+function findOwner(graph, projectRoot, rawPath) {
+  const file = normalizeForMatch(normalizeProjectRelativePath(projectRoot, rawPath));
+  let best = null;
+  for (const [nodePath, node] of graph.nodes) {
+    const mappingPaths = normalizeMappingPaths(node.meta.mapping).map(normalizeForMatch).filter((mappingPath) => mappingPath.length > 0);
+    for (const mappingPath of mappingPaths) {
+      if (file === mappingPath) {
+        return { file, nodePath, mappingPath };
+      }
+      if (file.startsWith(mappingPath + "/")) {
+        if (!best || best && mappingPath.length > best.mappingPath.length) {
+          best = { nodePath, mappingPath, exact: false };
+        }
+      }
+    }
+  }
+  return best ? { file, nodePath: best.nodePath, mappingPath: best.mappingPath } : { file, nodePath: null };
+}
+function registerOwnerCommand(program2) {
+  program2.command("owner").description("Find which graph node owns a source file").requiredOption("--file <path>", "File path (relative to repository root)").action(async (options) => {
+    try {
+      const projectRoot = process.cwd();
+      const graph = await loadGraph(projectRoot);
+      const result = findOwner(graph, projectRoot, options.file);
+      if (!result.nodePath) {
+        process.stdout.write(`${result.file} -> no graph coverage
+`);
+      } else {
+        process.stdout.write(`${result.file} -> ${result.nodePath}
+`);
+      }
+    } catch (error) {
+      process.stderr.write(`Error: ${error.message}
+`);
+      process.exit(1);
+    }
+  });
+}
+
+// src/core/dependency-resolver.ts
+import { execSync as execSync2 } from "child_process";
+import path12 from "path";
+var STRUCTURAL_RELATION_TYPES2 = /* @__PURE__ */ new Set(["uses", "calls", "extends", "implements"]);
+var EVENT_RELATION_TYPES2 = /* @__PURE__ */ new Set(["emits", "listens"]);
+function filterRelationType(relType, filter) {
+  if (filter === "all") return true;
+  if (filter === "structural") return STRUCTURAL_RELATION_TYPES2.has(relType);
+  if (filter === "event") return EVENT_RELATION_TYPES2.has(relType);
+  return false;
+}
+function buildDependencyTree(graph, nodePath, options = {}) {
+  const node = graph.nodes.get(nodePath);
+  if (!node) {
+    throw new Error(`Node not found: ${nodePath}`);
+  }
+  const maxDepth = options.depth ?? Infinity;
+  const typeFilter = options.relationType ?? "all";
+  function buildChildren(fromPath, currentDepth, branch) {
+    if (currentDepth >= maxDepth) return [];
+    const fromNode = graph.nodes.get(fromPath);
+    const children = [];
+    for (const rel of fromNode.meta.relations ?? []) {
+      if (!filterRelationType(rel.type, typeFilter)) continue;
+      if (!graph.nodes.has(rel.target)) continue;
+      if (branch.has(rel.target)) continue;
+      const targetNode = graph.nodes.get(rel.target);
+      const nextBranch = new Set(branch);
+      nextBranch.add(rel.target);
+      children.push({
+        nodePath: rel.target,
+        relationType: rel.type,
+        relationTarget: fromPath,
+        blackbox: targetNode.meta.blackbox ?? false,
+        children: buildChildren(rel.target, currentDepth + 1, nextBranch)
+      });
+    }
+    return children;
+  }
+  return buildChildren(nodePath, 0, /* @__PURE__ */ new Set([nodePath]));
+}
+function formatDependencyTree(graph, nodePath, options = {}) {
+  const roots = buildDependencyTree(graph, nodePath, options);
+  const lines = [nodePath];
+  function formatNode(node, prefix, isLast) {
+    const connector = isLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
+    const blackbox = node.blackbox ? " \u25A0 blackbox" : "";
+    lines.push(`${prefix}${connector}${node.relationType} ${node.nodePath}${blackbox}`);
+    const childPrefix = prefix + (isLast ? "    " : "\u2502   ");
+    const lastIdx = node.children.length - 1;
+    node.children.forEach((c, i) => formatNode(c, childPrefix, i === lastIdx));
+  }
+  roots.forEach((r, i) => formatNode(r, "", i === roots.length - 1));
+  return lines.join("\n");
+}
+
+// src/cli/deps.ts
+function registerDepsCommand(program2) {
+  program2.command("deps").description("Show direct and transitive node dependencies").requiredOption("--node <path>", "Node path relative to .yggdrasil/model/").option("--depth <n>", "Maximum depth for tree (when using --node)", (v) => parseInt(v, 10)).option("--type <type>", "Relation type filter: structural, event, all (default: all)", "all").action(async (options) => {
+    try {
+      const graph = await loadGraph(process.cwd());
+      const typeFilter = options.type === "structural" || options.type === "event" || options.type === "all" ? options.type : "all";
+      const nodePath = options.node.trim().replace(/\/$/, "");
+      const text = formatDependencyTree(graph, nodePath, {
+        depth: options.depth,
+        relationType: typeFilter
+      });
+      process.stdout.write(text + "\n");
+    } catch (error) {
+      process.stderr.write(`Error: ${error.message}
+`);
+      process.exit(1);
+    }
+  });
+}
+
+// src/core/graph-from-git.ts
+import { mkdtemp, rm } from "fs/promises";
+import { tmpdir } from "os";
+import path13 from "path";
+import { execSync as execSync3 } from "child_process";
+async function loadGraphFromRef(projectRoot, ref = "HEAD") {
+  const yggPath = ".yggdrasil";
+  let tmpDir = null;
+  try {
+    execSync3(`git rev-parse ${ref}`, { cwd: projectRoot, stdio: "pipe" });
+  } catch {
+    return null;
+  }
+  try {
+    tmpDir = await mkdtemp(path13.join(tmpdir(), "ygg-git-"));
+    const archivePath = path13.join(tmpDir, "archive.tar");
+    execSync3(`git archive ${ref} ${yggPath} -o "${archivePath}"`, {
+      cwd: projectRoot,
+      stdio: "pipe"
+    });
+    execSync3(`tar -xf "${archivePath}" -C "${tmpDir}"`, { stdio: "pipe" });
+    const graph = await loadGraph(tmpDir);
+    return graph;
+  } catch {
+    return null;
+  } finally {
+    if (tmpDir) {
+      await rm(tmpDir, { recursive: true, force: true });
+    }
+  }
+}
+
+// src/cli/impact.ts
+var STRUCTURAL_TYPES = /* @__PURE__ */ new Set(["uses", "calls", "extends", "implements"]);
+function collectReverseDependents(graph, targetNode) {
+  const reverse = /* @__PURE__ */ new Map();
+  const relationFrom = /* @__PURE__ */ new Map();
+  for (const [nodePath, node] of graph.nodes) {
+    for (const rel of node.meta.relations ?? []) {
+      if (!STRUCTURAL_TYPES.has(rel.type)) continue;
+      const deps = reverse.get(rel.target) ?? /* @__PURE__ */ new Set();
+      deps.add(nodePath);
+      reverse.set(rel.target, deps);
+      relationFrom.set(`${nodePath}->${rel.target}`, {
+        type: rel.type,
+        consumes: rel.consumes
+      });
+    }
+  }
+  const direct = [...reverse.get(targetNode) ?? []].sort();
+  const seen = new Set(direct);
+  const queue = [...direct];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    for (const next of reverse.get(current) ?? []) {
+      if (seen.has(next)) continue;
+      seen.add(next);
+      queue.push(next);
+    }
+  }
+  return {
+    direct,
+    transitive: [...seen].sort(),
+    reverse,
+    relationFrom
+  };
+}
+function buildTransitiveChains(targetNode, direct, transitive, reverse) {
+  const directSet = new Set(direct);
+  const transitiveOnly = transitive.filter((t) => !directSet.has(t));
+  if (transitiveOnly.length === 0) return [];
+  const parent = /* @__PURE__ */ new Map();
+  const queue = [targetNode];
+  const visited = /* @__PURE__ */ new Set([targetNode]);
+  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);
+    }
+  }
+  const chains = [];
+  for (const node of transitiveOnly) {
+    const path15 = [];
+    let current = node;
+    while (current) {
+      path15.unshift(current);
+      current = parent.get(current);
+    }
+    if (path15.length >= 2) {
+      chains.push(path15.map((p) => `<- ${p}`).join(" "));
+    }
+  }
+  return chains.sort();
+}
+function registerImpactCommand(program2) {
+  program2.command("impact").description("Show reverse dependency impact for a node").requiredOption("--node <path>", "Node path relative to .yggdrasil/model/").option("--simulate", "Simulate context package impact (compare HEAD vs current)").action(async (options) => {
+    try {
+      const graph = await loadGraph(process.cwd());
+      const nodePath = options.node.trim().replace(/\/$/, "");
+      if (!graph.nodes.has(nodePath)) {
+        process.stderr.write(`Node not found: ${nodePath}
+`);
+        process.exit(1);
+      }
+      const { direct, transitive, reverse, relationFrom } = collectReverseDependents(
+        graph,
+        nodePath
+      );
+      const chains = buildTransitiveChains(nodePath, direct, transitive, reverse);
+      const flows = [];
+      for (const flow of graph.flows) {
+        if (flow.nodes.includes(nodePath)) {
+          flows.push(flow.name);
+        }
+      }
+      const aspectsInScope = [];
+      const targetNode = graph.nodes.get(nodePath);
+      const targetTags = new Set(targetNode.meta.tags ?? []);
+      for (const aspect of graph.aspects) {
+        if (targetTags.has(aspect.tag)) {
+          aspectsInScope.push(aspect.name);
+        }
+      }
+      const knowledgeInScope = [];
+      for (const k of graph.knowledge) {
+        if (k.scope === "global") {
+          knowledgeInScope.push(k.path);
+          continue;
+        }
+        if (typeof k.scope === "object" && "tags" in k.scope) {
+          if (k.scope.tags.some((t) => targetTags.has(t))) {
+            knowledgeInScope.push(k.path);
+          }
+          continue;
+        }
+        if (typeof k.scope === "object" && "nodes" in k.scope) {
+          if (k.scope.nodes.includes(nodePath)) {
+            knowledgeInScope.push(k.path);
+          }
+        }
+      }
+      const budget = graph.config.quality?.context_budget ?? { warning: 5e3, error: 1e4 };
+      process.stdout.write(`Impact of changes in ${nodePath}:
+
+`);
+      process.stdout.write("Directly dependent:\n");
+      if (direct.length === 0) {
+        process.stdout.write("  (none)\n");
+      } else {
+        for (const dep of direct) {
+          const rel = relationFrom.get(`${dep}->${nodePath}`);
+          const annot = rel?.consumes?.length ? ` (${rel.type}, you consume: ${rel.consumes.join(", ")})` : rel ? ` (${rel.type})` : "";
+          process.stdout.write(`  <- ${dep}${annot}
+`);
+        }
+      }
+      process.stdout.write("\nTransitively dependent:\n");
+      if (chains.length === 0) {
+        process.stdout.write("  (none)\n");
+      } else {
+        for (const chain of chains) {
+          process.stdout.write(`  ${chain}
+`);
+        }
+      }
+      process.stdout.write(`
+Flows: ${flows.length > 0 ? flows.join(", ") : "(none)"}
+`);
+      process.stdout.write(
+        `Aspects (scope covers node): ${aspectsInScope.length > 0 ? aspectsInScope.join(", ") : "(none)"}
+`
+      );
+      process.stdout.write(
+        `Knowledge (scope covers node): ${knowledgeInScope.length > 0 ? knowledgeInScope.join(", ") : "(none)"}
+`
+      );
+      process.stdout.write(
+        `
+Total scope: ${transitive.length} nodes, ${flows.length} flows, ${aspectsInScope.length} aspects, ${knowledgeInScope.length} knowledge
+`
+      );
+      if (options.simulate && transitive.length > 0) {
+        process.stdout.write("\nChanges in context packages:\n\n");
+        const baselineGraph = await loadGraphFromRef(process.cwd(), "HEAD");
+        const driftReport = await detectDrift(graph);
+        const driftByNode = new Map(driftReport.entries.map((e) => [e.nodePath, e]));
+        for (const dep of transitive) {
+          try {
+            const pkg = await buildContext(graph, dep);
+            const status = pkg.tokenCount >= budget.error ? "error" : pkg.tokenCount >= budget.warning ? "warning" : "ok";
+            let baselineTokens = null;
+            if (baselineGraph?.nodes.has(dep)) {
+              try {
+                const baselinePkg = await buildContext(baselineGraph, dep);
+                baselineTokens = baselinePkg.tokenCount;
+              } catch {
+              }
+            }
+            const hasDepOnTarget = graph.nodes.get(dep)?.meta.relations?.some(
+              (r) => r.target === nodePath && STRUCTURAL_TYPES.has(r.type)
+            );
+            const changedLine = hasDepOnTarget ? `  + Changed dependency interface: ${nodePath}
+` : "";
+            const budgetLine = baselineTokens !== null ? `  Budget: ${baselineTokens} -> ${pkg.tokenCount} tokens (${status})
+` : `  Budget: ${pkg.tokenCount} tokens (${status})
+`;
+            const driftEntry = driftByNode.get(dep);
+            const driftLine = driftEntry && driftEntry.status !== "ok" ? `  Mapped files (on-disk): ${driftEntry.status}${driftEntry.details ? ` (${driftEntry.details})` : ""}
+` : driftEntry ? `  Mapped files (on-disk): ok
+` : "";
+            process.stdout.write(`${dep}:
+${changedLine}${budgetLine}${driftLine}
+`);
+          } catch {
+            process.stdout.write(`${dep}:
+  failed to build context
+
+`);
+          }
+        }
+      }
+    } catch (error) {
+      process.stderr.write(`Error: ${error.message}
+`);
+      process.exit(1);
+    }
+  });
+}
+
+// src/io/journal-store.ts
+import { readFile as readFile13, writeFile as writeFile4, mkdir as mkdir3, rename, access as access2 } from "fs/promises";
+import { parse as parseYaml8, stringify as stringifyYaml2 } from "yaml";
+import path14 from "path";
+var JOURNAL_FILE = ".journal.yaml";
+var ARCHIVE_DIR = "journals-archive";
+async function readJournal(yggRoot) {
+  const filePath = path14.join(yggRoot, JOURNAL_FILE);
+  try {
+    const content = await readFile13(filePath, "utf-8");
+    const raw = parseYaml8(content);
+    const entries = raw.entries ?? [];
+    return Array.isArray(entries) ? entries : [];
+  } catch {
+    return [];
+  }
+}
+async function appendJournalEntry(yggRoot, note, target) {
+  const entries = await readJournal(yggRoot);
+  const at = (/* @__PURE__ */ new Date()).toISOString();
+  const entry = target ? { at, target, note } : { at, note };
+  entries.push(entry);
+  const filePath = path14.join(yggRoot, JOURNAL_FILE);
+  const content = stringifyYaml2({ entries });
+  await writeFile4(filePath, content, "utf-8");
+  return entry;
+}
+async function archiveJournal(yggRoot) {
+  const journalPath = path14.join(yggRoot, JOURNAL_FILE);
+  try {
+    await access2(journalPath);
+  } catch {
+    return null;
+  }
+  const entries = await readJournal(yggRoot);
+  if (entries.length === 0) return null;
+  const archiveDir = path14.join(yggRoot, ARCHIVE_DIR);
+  await mkdir3(archiveDir, { recursive: true });
+  const now = /* @__PURE__ */ new Date();
+  const timestamp = `${now.getUTCFullYear()}${String(now.getUTCMonth() + 1).padStart(2, "0")}${String(now.getUTCDate()).padStart(2, "0")}-${String(now.getUTCHours()).padStart(2, "0")}${String(now.getUTCMinutes()).padStart(2, "0")}${String(now.getUTCSeconds()).padStart(2, "0")}`;
+  const archiveName = `.journal.${timestamp}.yaml`;
+  const archivePath = path14.join(archiveDir, archiveName);
+  await rename(journalPath, archivePath);
+  return { archiveName, entryCount: entries.length };
+}
+
+// src/cli/journal-add.ts
+function registerJournalAddCommand(program2) {
+  program2.command("journal-add").description("Add a note to the session journal").requiredOption("--note <text>", "Note content").option("--target <node-path>", "Node path this note relates to").action(async (options) => {
+    try {
+      const projectRoot = process.cwd();
+      const yggRoot = await findYggRoot(projectRoot);
+      await appendJournalEntry(yggRoot, options.note, options.target);
+      const entries = await readJournal(yggRoot);
+      process.stdout.write(`Note added to journal (${entries.length} entries total)
+`);
+    } catch (error) {
+      process.stderr.write(`Error: ${error.message}
+`);
+      process.exit(1);
+    }
+  });
+}
+
+// src/cli/journal-read.ts
+function registerJournalReadCommand(program2) {
+  program2.command("journal-read").description("List pending journal entries").action(async () => {
+    try {
+      const projectRoot = process.cwd();
+      const yggRoot = await findYggRoot(projectRoot);
+      const entries = await readJournal(yggRoot);
+      if (entries.length === 0) {
+        process.stdout.write("Session journal: empty (clean state)\n");
+        return;
+      }
+      process.stdout.write(`Session journal (${entries.length} entries):
+
+`);
+      for (const e of entries) {
+        const date = e.at.slice(0, 19).replace("T", " ");
+        const target = e.target ? ` ${e.target}` : "";
+        process.stdout.write(`[${date}]${target}
+  ${e.note}
+
+`);
+      }
+    } catch (error) {
+      process.stderr.write(`Error: ${error.message}
+`);
+      process.exit(1);
+    }
+  });
+}
+
+// src/cli/journal-archive.ts
+function registerJournalArchiveCommand(program2) {
+  program2.command("journal-archive").description("Archive journal after consolidating notes to graph").action(async () => {
+    try {
+      const projectRoot = process.cwd();
+      const yggRoot = await findYggRoot(projectRoot);
+      const result = await archiveJournal(yggRoot);
+      if (!result) {
+        process.stdout.write("No active journal - nothing to archive.\n");
+        return;
+      }
+      process.stdout.write(
+        `Archived journal (${result.entryCount} entries) -> journals-archive/${result.archiveName}
+`
+      );
+    } catch (error) {
+      process.stderr.write(`Error: ${error.message}
+`);
+      process.exit(1);
+    }
+  });
+}
+
+// src/bin.ts
+var program = new Command();
+program.name("yg").description("Yggdrasil \u2014 architectural knowledge infrastructure for AI agents").version("0.1.0");
+registerInitCommand(program);
+registerBuildCommand(program);
+registerValidateCommand(program);
+registerDriftCommand(program);
+registerDriftSyncCommand(program);
+registerStatusCommand(program);
+registerTreeCommand(program);
+registerOwnerCommand(program);
+registerDepsCommand(program);
+registerImpactCommand(program);
+registerJournalAddCommand(program);
+registerJournalReadCommand(program);
+registerJournalArchiveCommand(program);
+program.parse();
+//# sourceMappingURL=bin.js.map